Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Configuration reference

Everything is configured with environment variables. The server checks all of them at startup and refuses to start with a list of every problem it found, so a typo never leaves it half configured.

General rules:

  • An empty value counts as unset.
  • Every variable can also be read from a file by appending _FILE to its name, for example ICLOUD_APP_PASSWORD_FILE=/run/secrets/icloud. A value set directly wins over the file, and a trailing newline in the file is ignored. Use this for secrets with Docker or Kubernetes secrets.
  • Booleans accept true, false, 1, 0, yes, no, on and off.
  • Lists are comma separated; spaces around names are ignored.

Server and HTTP

VariableRequiredDefaultExampleDescription
PUBLIC_URLyeshttps://icloud.example.comExternal base URL clients use, without a path. Must be https; http is accepted only for localhost
BIND_ADDRno0.0.0.0:8443127.0.0.1:8443Listen address. It must listen on loopback (0.0.0.0 does) so --healthcheck can reach 127.0.0.1
TLS_CERT_PATH, TLS_KEY_PATHno/certs/fullchain.pem, /certs/privkey.pemPEM certificate chain and private key. Both or neither; reloaded automatically when the files change. See TLS and public access
INSECURE_HTTPnofalsetrueServe plain HTTP. Only when TLS is terminated in front of the server on a network you trust
ALLOWED_ORIGINSnohttps://app.example.comExtra Origin values accepted on MCP requests, comma separated. The PUBLIC_URL origin is always allowed
TRUSTED_PROXIESno10.0.0.2,10.0.0.3Proxy IP addresses whose X-Forwarded-For is trusted for login rate limiting

Services

VariableRequiredDefaultExampleDescription
ICLOUD_SERVICESnoall (mail,calendar,contacts)mail,calendarServices to run. An unknown name or an empty list stops startup. A service that is not selected is not mounted and does not read its variables
ICLOUD_READ_ONLYnononecontacts or allServices whose write tools are hidden and refused, on their own endpoint and under /mcp. An unknown name stops startup. See Security
ICLOUD_COMBINEDnotruefalseServe the combined endpoint /mcp. With false, /mcp returns 404

OAuth and tokens

VariableRequiredDefaultExampleDescription
OAUTH_SIGNING_KEYyesoutput of openssl rand -hex 32Key that signs OAuth tokens, at least 32 bytes. Changing it signs every client out
OAUTH_ADMIN_PASSWORDyesa passphrasePassword for the server’s login page, at least 12 characters (the server warns below 15). Changing it signs every connector out
MCP_AUTH_TOKENnooutput of openssl rand -hex 32Static bearer token accepted on every endpoint, for clients that can send a header. Treat it like the admin password. Must not contain exactly two dots

iCloud account

VariableRequiredDefaultExampleDescription
ICLOUD_EMAILyesyou@icloud.comYour Apple ID or iCloud address
ICLOUD_APP_PASSWORDyesxxxx-xxxx-xxxx-xxxxApp-specific password, used by every service

Mail

VariableRequiredDefaultExampleDescription
ICLOUD_USERNAMEnoICLOUD_EMAILyouIMAP and SMTP login, if it differs from the address
ICLOUD_FROM_NAMEnoAlex ExampleDisplay name on drafts
ICLOUD_ALLOW_SENDnofalsetrueRegisters the send_draft tool. Without it nothing can be sent
MAX_ATTACHMENT_BYTESno10485760 (10 MiB)20971520Largest attachment get_attachment returns, and the largest decoded total of the attachments on one create_draft or create_reply_draft
CACHE_MAX_BYTESno67108864 (64 MiB)0In-memory cache of message bodies; 0 disables it
IMAP_IDLE_TIMEOUTno600300Seconds before an idle IMAP connection is closed

Calendar

VariableRequiredDefaultExampleDescription
CALENDAR_TIMEZONEnoEurope/LondonAmerica/New_YorkIANA time zone used to read and show times when no override is set. An unknown name stops startup
ICLOUD_ALLOW_INVITESnofalsetrueAllows changing attendees (iCloud emails them) and registers respond_to_invitation
CALDAV_URLnohttps://caldav.icloud.comhttp://127.0.0.1:8080CalDAV entry point. Must be https, except a loopback address for testing

Contacts

VariableRequiredDefaultExampleDescription
CONTACTS_TIMEZONEnoUTCEurope/LondonIANA time zone that decides “today” for upcoming_dates. An unknown name stops startup
CARDDAV_URLnohttps://contacts.icloud.comhttp://127.0.0.1:8080CardDAV entry point. Must be https, except a loopback address for testing

Logging, metrics and audit

VariableRequiredDefaultExampleDescription
LOG_LEVELnoinfoinfo,mcp_icloud_contacts=debugLog filter in tracing syntax. Targets: mcp_icloud_mail, mcp_icloud_calendar, mcp_icloud_contacts, mcp_server_core. The audit target always stays on at info
LOG_FORMATnojsonprettyjson or pretty
DEBUGnofalsetrueDebug logging with content redacted: tool arguments, result sizes, protocol command labels and status codes. Never IMAP protocol lines, bodies or credentials
DEBUG_UNSAFE_LOG_CONTENTnofalsetrueAlso logs full tool results and CalDAV and CardDAV bodies, which puts your mail, event and contact content in the logs. A warning is printed at startup. Credentials are never logged
METRICS_ADDRno0.0.0.0:9090Starts a separate plain-HTTP Prometheus listener. Keep it on an internal network
OTEL_EXPORTER_OTLP_ENDPOINTnohttps://otel.example.comExports traces over OTLP/HTTP. The standard OTEL_EXPORTER_OTLP_HEADERS is honoured. Nothing is exported unless it is set
AUDIT_LOG_PATHno/audit/audit.jsonlFile every write tool call is appended to as one JSON line (created with mode 0600). Audit lines are always logged too. See Security

A complete example

ICLOUD_EMAIL=you@icloud.com
ICLOUD_APP_PASSWORD_FILE=/run/secrets/icloud_app_password
PUBLIC_URL=https://icloud.example.com
OAUTH_SIGNING_KEY_FILE=/run/secrets/oauth_signing_key
OAUTH_ADMIN_PASSWORD_FILE=/run/secrets/oauth_admin_password
MCP_AUTH_TOKEN_FILE=/run/secrets/mcp_auth_token
ICLOUD_SERVICES=mail,calendar,contacts
ICLOUD_READ_ONLY=mail
CALENDAR_TIMEZONE=Europe/London
CONTACTS_TIMEZONE=Europe/London
AUDIT_LOG_PATH=/audit/audit.jsonl
LOG_FORMAT=json