Skip to content
MCP server

icloud-mcp

iCloud Calendar MCP server with optional Contacts and Mail, gated by permissions

Runs locallyStatus and history
Install
Pricing
Open source
Platforms
CLI, macOS, Linux
Runs
Locally
Version
1.1.1
Listing updated
today

Similar MCP servers

About icloud-mcp

icloud-mcp is an open-source MCP server for productivity. It runs locally on your machine and is started by your AI client.

Built for headless machines, this server talks to iCloud over open protocols: CalDAV for calendars, CardDAV for contacts, and IMAP and SMTP for mail. It uses app-specific passwords and avoids macOS frameworks, browser automation and private Apple APIs. The README is blunt that all enabled domains share one process, so a compromise could expose every loaded credential.

Nothing is on by default beyond calendar reads. ICLOUD_MCP_PERMISSIONS names each capability (for example calendar.write, mail.send), ICLOUD_MCP_READ_ONLY=true strips every mutation tool from discovery, and ICLOUD_MCP_RESOURCE_SCOPES can restrict an agent to named calendars, address books or mailboxes. Sending mail also requires a recipient policy. The default profile registers 7 tools and the full set is 24.

There is no telemetry. Audit records go to stderr with hashed resource tokens, and an -doctor command runs read-only connectivity checks. Binaries ship as MCPB bundles for Linux and macOS.

Install

Run in a terminal

claude mcp add icloud-mcp -- npx -y https://github.com/ThomasCrouzet/icloud-mcp/releases/download/v1.1.1/icloud-mcp-v1.1.1-linux-amd64.mcpb

Add to claude_desktop_config.json

{
  "mcpServers": {
    "icloud-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/ThomasCrouzet/icloud-mcp/releases/download/v1.1.1/icloud-mcp-v1.1.1-linux-amd64.mcpb"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "icloud-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/ThomasCrouzet/icloud-mcp/releases/download/v1.1.1/icloud-mcp-v1.1.1-linux-amd64.mcpb"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

Add to .vscode/mcp.json

{
  "servers": {
    "icloud-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/ThomasCrouzet/icloud-mcp/releases/download/v1.1.1/icloud-mcp-v1.1.1-linux-amd64.mcpb"
      ]
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "icloud-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/ThomasCrouzet/icloud-mcp/releases/download/v1.1.1/icloud-mcp-v1.1.1-linux-amd64.mcpb"
      ]
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "icloud-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/ThomasCrouzet/icloud-mcp/releases/download/v1.1.1/icloud-mcp-v1.1.1-linux-amd64.mcpb"
      ]
    }
  }
}

Using several servers? Build one config file with the MCP config generator.

Tools this server provides (7)

Taken from the project documentation; the running server may differ.

icloud_capabilities
Show enabled domains, effective capabilities, version and tool names.
list_calendars
List calendar names and paths.
search_events
Search events in a time range, with filters and paging.
update_event
Update an event; a conditional calendar write.
get_message
Get message metadata and bounded plain text.
send_message
Send a plain-text message to allowed recipients.
reply_message
Reply to a message, preserving conversation headers.

What it does

Calendar search and free time
Search events, find free slots, and create, update or delete events when permitted.
Optional contacts
Search and edit vCard contacts once enabled.
Optional mail
List mailboxes, read messages without changing read state, and send or reply.
Capability gates
Each domain and each mutation needs an explicit permission.
Resource scopes
Limit access to specific calendars, address books or mailboxes.
Doctor command
Read-only checks that each enabled domain can be reached.
Idempotent sends
Keyed calls reuse one submission instead of sending twice.

Good for

  • Asking an assistant to find a free hour across calendars
  • Searching and replying to iCloud mail from an agent
  • Creating calendar events from a chat on a headless server
  • Giving an agent read-only access to contacts

Pricing

Open source

Free to run; requires an iCloud account with an app-specific password

icloud-mcp FAQ

What account do I need?

An Apple Account with iCloud Calendar and an app-specific password; Mail needs a full iCloud Mail address.

Can the agent send mail by default?

No. Sending needs the mail.send permission and a recipient policy.

Does it collect telemetry?

No. The README says there is no telemetry or crash reporting, and it writes no local data files.

How many tools does it expose?

Seven in the default read-only profile and 24 with every capability enabled.

Is icloud-mcp free?

Yes. icloud-mcp is open source, so you can use and self-host it for free.

How do I add icloud-mcp to Claude Code?

Run this command in your terminal: claude mcp add icloud-mcp -- npx -y https://github.com/ThomasCrouzet/icloud-mcp/releases/download/v1.1.1/icloud-mcp-v1.1.1-linux-amd64.mcpb

What are the best alternatives to icloud-mcp?

The closest alternatives to icloud-mcp are TrendRadar, Ha MCP, Concord MCP, Getmitra and note1.

Where this comes from

  • Description: written from the project's README.
  • Install steps: from the official MCP Registry entry.

How AIPoweredBot checks servers