icloud-mcp

Overview

This MCP server enables Claude to interact with your Apple services in two modes:

Local Mode (Default) - macOS Only

Uses AppleScript to access native macOS apps. Faster, works offline, more services.

Cloud Mode - Works Anywhere

Uses iCloud protocols (IMAP, CalDAV, CardDAV). Requires app-specific password.

Features

• 31 Tools in local mode (17 in cloud mode)
• Dual Mode - switch between local (fast) and cloud (remote access)
• 7 Services - Email, Calendar, Contacts, Reminders, Notes, Messages, Safari
• Secure Authentication - AppleScript permissions or app-specific passwords
• Full CRUD - create, read, update, delete across services

Installation

# Clone the repository
git clone https://github.com/MrGo2/icloud-mcp.git
cd icloud-mcp

# Install dependencies
npm install

# Configure (optional for local mode)
cp .env.example .env

Configuration

Local Mode (Default)

No configuration needed! Just run:

npm start

On first use, macOS will prompt for access to each app. Grant permission in System Settings > Privacy & Security > Automation.

Cloud Mode

1. Generate an App-Specific Password

   • Go to appleid.apple.com
   • Sign in → Security → App-Specific Passwords → Generate
   • Name it iCloud MCP and copy the 16-character password

2. Configure .env

   USE_LOCAL_MODE=false
   ICLOUD_EMAIL=your-email@icloud.com
   ICLOUD_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx
   

Add to Claude Desktop

Add to your Claude Desktop MCP settings (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "apple": {
      "command": "node",
      "args": ["/path/to/icloud-mcp/index.js"]
    }
  }
}

Tools

Authentication (2)

Email (6)

Calendar (5)

Contacts (5)

Reminders (7) - Local Only

Notes (5) - Local Only

Messages (1) - Local Only

Safari (4) - Local Only

Architecture

icloud-mcp/
├── index.js              # MCP server (mode switching)
├── config.js             # Configuration
├── auth/                 # Credential management
├── email/
│   ├── imap-client.js    # Cloud: IMAP
│   ├── smtp-client.js    # Cloud: SMTP
│   ├── local-client.js   # Local: Mail.app
│   └── index.js
├── calendar/
│   ├── caldav-client.js  # Cloud: CalDAV
│   ├── local-client.js   # Local: Calendar.app
│   └── index.js
├── contacts/
│   ├── carddav-client.js # Cloud: CardDAV
│   ├── local-client.js   # Local: Contacts.app
│   └── index.js
├── reminders/            # Local only
├── notes/                # Local only
├── messages/             # Local only
├── safari/               # Local only
└── utils/
    ├── applescript.js    # AppleScript executor
    ├── date-utils.js
    └── error-handler.js

Usage Examples

List Reminders

"Show me my reminders for today"

Create a Reminder

"Create a reminder to buy milk tomorrow at 5pm"

Send a Message

"Send an iMessage to +34612345678 saying I'll be there in 10 minutes"

Check Safari Tabs

"What tabs do I have open in Safari?"

Send Email

"Send an email to john@example.com with subject 'Meeting Tomorrow'"

Mode Comparison

Limitations

Troubleshooting

Development

# Run in local mode (default)
npm start

# Run in cloud mode
USE_LOCAL_MODE=false npm start

# Test with MCP Inspector
npm run inspect

License

MIT © Carlos Lorenzo