MCP Server

io.github.eodozzy/icloud-mcp MCP Server

Name: io.github.eodozzy/icloud-mcp MCP Server
Author: io.github.eodozzy

io.github.eodozzy/icloud-mcp

Repository Registry

What is the io.github.eodozzy/icloud-mcp MCP server?

Read-only-by-default MCP server for iCloud mail, calendar, and contacts (IMAP/CalDAV/CardDAV).

How to install io.github.eodozzy/icloud-mcp

Copy-paste configuration for popular MCP clients.

transport: stdio

Config generated by PluginBench — verify against the source before use.

Environment / auth

ICLOUD_USERNAME
required
Your Apple ID email (the IMAP/CalDAV username).
ICLOUD_KEYRING_SERVICE
OS-keyring service name to read the app-specific password from. Default: icloud-mcp. Set to reuse an existing entry.
ICLOUD_APP_PASSWORD
secret
App-specific password. Fallback only; preferred storage is the OS keyring. Used only when no keyring entry is found.
ICLOUD_ENABLE_WRITES
Enable mutating tools (send/reply/forward mail, create/update/delete event & contact). Off by default; each write still requires interactive confirmation. Accepts 1/true/yes/on.
ICLOUD_IMAP_HOST
IMAP host override. Default: imap.mail.me.com
ICLOUD_IMAP_PORT
IMAP port override. Default: 993
ICLOUD_SMTP_HOST
SMTP host override (used only by write/send tools). Default: smtp.mail.me.com
ICLOUD_SMTP_PORT
SMTP port override. Default: 587
ICLOUD_CALDAV_URL
CalDAV base URL override. Default: https://caldav.icloud.com/
ICLOUD_CARDDAV_URL
CardDAV base URL override. Default: https://contacts.icloud.com/
ICLOUD_TZ
IANA timezone for rendering/scoping events. Default: system local time.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "icloud-mcp": {
      "command": "uvx",
      "args": [
        "icloud-mcp"
      ],
      "env": {
        "ICLOUD_USERNAME": "<YOUR_ICLOUD_USERNAME>",
        "ICLOUD_KEYRING_SERVICE": "<YOUR_ICLOUD_KEYRING_SERVICE>",
        "ICLOUD_APP_PASSWORD": "<YOUR_ICLOUD_APP_PASSWORD>",
        "ICLOUD_ENABLE_WRITES": "<YOUR_ICLOUD_ENABLE_WRITES>",
        "ICLOUD_IMAP_HOST": "<YOUR_ICLOUD_IMAP_HOST>",
        "ICLOUD_IMAP_PORT": "<YOUR_ICLOUD_IMAP_PORT>",
        "ICLOUD_SMTP_HOST": "<YOUR_ICLOUD_SMTP_HOST>",
        "ICLOUD_SMTP_PORT": "<YOUR_ICLOUD_SMTP_PORT>",
        "ICLOUD_CALDAV_URL": "<YOUR_ICLOUD_CALDAV_URL>",
        "ICLOUD_CARDDAV_URL": "<YOUR_ICLOUD_CARDDAV_URL>",
        "ICLOUD_TZ": "<YOUR_ICLOUD_TZ>"
      }
    }
  }
}

Cursor

~/.cursor/mcp.json

{
  "mcpServers": {
    "icloud-mcp": {
      "command": "uvx",
      "args": [
        "icloud-mcp"
      ],
      "env": {
        "ICLOUD_USERNAME": "<YOUR_ICLOUD_USERNAME>",
        "ICLOUD_KEYRING_SERVICE": "<YOUR_ICLOUD_KEYRING_SERVICE>",
        "ICLOUD_APP_PASSWORD": "<YOUR_ICLOUD_APP_PASSWORD>",
        "ICLOUD_ENABLE_WRITES": "<YOUR_ICLOUD_ENABLE_WRITES>",
        "ICLOUD_IMAP_HOST": "<YOUR_ICLOUD_IMAP_HOST>",
        "ICLOUD_IMAP_PORT": "<YOUR_ICLOUD_IMAP_PORT>",
        "ICLOUD_SMTP_HOST": "<YOUR_ICLOUD_SMTP_HOST>",
        "ICLOUD_SMTP_PORT": "<YOUR_ICLOUD_SMTP_PORT>",
        "ICLOUD_CALDAV_URL": "<YOUR_ICLOUD_CALDAV_URL>",
        "ICLOUD_CARDDAV_URL": "<YOUR_ICLOUD_CARDDAV_URL>",
        "ICLOUD_TZ": "<YOUR_ICLOUD_TZ>"
      }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "icloud-mcp": {
      "command": "uvx",
      "args": [
        "icloud-mcp"
      ],
      "env": {
        "ICLOUD_USERNAME": "<YOUR_ICLOUD_USERNAME>",
        "ICLOUD_KEYRING_SERVICE": "<YOUR_ICLOUD_KEYRING_SERVICE>",
        "ICLOUD_APP_PASSWORD": "<YOUR_ICLOUD_APP_PASSWORD>",
        "ICLOUD_ENABLE_WRITES": "<YOUR_ICLOUD_ENABLE_WRITES>",
        "ICLOUD_IMAP_HOST": "<YOUR_ICLOUD_IMAP_HOST>",
        "ICLOUD_IMAP_PORT": "<YOUR_ICLOUD_IMAP_PORT>",
        "ICLOUD_SMTP_HOST": "<YOUR_ICLOUD_SMTP_HOST>",
        "ICLOUD_SMTP_PORT": "<YOUR_ICLOUD_SMTP_PORT>",
        "ICLOUD_CALDAV_URL": "<YOUR_ICLOUD_CALDAV_URL>",
        "ICLOUD_CARDDAV_URL": "<YOUR_ICLOUD_CARDDAV_URL>",
        "ICLOUD_TZ": "<YOUR_ICLOUD_TZ>"
      }
    }
  }
}

VS Code

.vscode/mcp.json

{
  "servers": {
    "icloud-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "icloud-mcp"
      ],
      "env": {
        "ICLOUD_USERNAME": "<YOUR_ICLOUD_USERNAME>",
        "ICLOUD_KEYRING_SERVICE": "<YOUR_ICLOUD_KEYRING_SERVICE>",
        "ICLOUD_APP_PASSWORD": "<YOUR_ICLOUD_APP_PASSWORD>",
        "ICLOUD_ENABLE_WRITES": "<YOUR_ICLOUD_ENABLE_WRITES>",
        "ICLOUD_IMAP_HOST": "<YOUR_ICLOUD_IMAP_HOST>",
        "ICLOUD_IMAP_PORT": "<YOUR_ICLOUD_IMAP_PORT>",
        "ICLOUD_SMTP_HOST": "<YOUR_ICLOUD_SMTP_HOST>",
        "ICLOUD_SMTP_PORT": "<YOUR_ICLOUD_SMTP_PORT>",
        "ICLOUD_CALDAV_URL": "<YOUR_ICLOUD_CALDAV_URL>",
        "ICLOUD_CARDDAV_URL": "<YOUR_ICLOUD_CARDDAV_URL>",
        "ICLOUD_TZ": "<YOUR_ICLOUD_TZ>"
      }
    }
  }
}

Claude Code

claude mcp add icloud-mcp --env ICLOUD_USERNAME=<YOUR_ICLOUD_USERNAME> --env ICLOUD_KEYRING_SERVICE=<YOUR_ICLOUD_KEYRING_SERVICE> --env ICLOUD_APP_PASSWORD=<YOUR_ICLOUD_APP_PASSWORD> --env ICLOUD_ENABLE_WRITES=<YOUR_ICLOUD_ENABLE_WRITES> --env ICLOUD_IMAP_HOST=<YOUR_ICLOUD_IMAP_HOST> --env ICLOUD_IMAP_PORT=<YOUR_ICLOUD_IMAP_PORT> --env ICLOUD_SMTP_HOST=<YOUR_ICLOUD_SMTP_HOST> --env ICLOUD_SMTP_PORT=<YOUR_ICLOUD_SMTP_PORT> --env ICLOUD_CALDAV_URL=<YOUR_ICLOUD_CALDAV_URL> --env ICLOUD_CARDDAV_URL=<YOUR_ICLOUD_CARDDAV_URL> --env ICLOUD_TZ=<YOUR_ICLOUD_TZ> -- uvx icloud-mcp