iCloud MCP Server

MCP (Model Context Protocol) server for iCloud integration, providing tools for managing calendars (CalDAV), contacts (CardDAV), and email (IMAP/SMTP).

Features

• Stateless Architecture: No state stored between requests

• Full CRUD Operations: Complete management of calendars, contacts, and email

• Flexible Authentication: Via headers or environment variables

• Multiple Transports: stdio (local) or Streamable HTTP (server)

• Docker Support: Easy deployment with Docker and Docker Compose

Related MCP server: mail-cal-drive-mcp

Supported Operations

Calendar Tools (CalDAV)

• calendar_list_calendars - List all calendars

• calendar_list_events - List events with date filtering

• calendar_create_event - Create new event

• calendar_update_event - Update existing event

• calendar_delete_event - Delete event

• calendar_search_events - Search events by text

Contacts Tools (CardDAV)

• contacts_list - List all contacts

• contacts_get - Get specific contact

• contacts_create - Create new contact (name, phones, emails, addresses, organization, title)

• contacts_update - Update existing contact

• contacts_delete - Delete contact

• contacts_search - Search contacts by text

Email Tools (IMAP/SMTP)

• email_list_folders - List mail folders

• email_list_messages - List messages in folder

• email_get_message - Get full message details

• email_get_messages - Get multiple messages at once (bulk fetch)

• email_search - Search messages by text

• email_send - Send email via SMTP

• email_move - Move message to folder

• email_delete - Delete or trash message

• email_mark_read - Mark message as read

• email_mark_unread - Mark message as unread

Installation

Prerequisites

• Python 3.10 - 3.12 (Python 3.13+ not yet supported due to dependency compatibility)

• iCloud account with App-Specific Password (Generate here)

Local Installation

# Clone repository
git clone <repository-url>
cd icloud-mcp

# Create virtual environment with Python 3.10-3.12
python3.12 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install package in editable mode
pip install -e .

# Configure environment
cp .env.example .env
# Edit .env with your credentials

Docker Installation

# Clone repository
git clone <repository-url>
cd icloud-mcp

# Configure environment
cp .env.example .env
# Edit .env with your credentials

# Build and run with Docker Compose
docker-compose up -d

Configuration

Environment Variables

Create a .env file with the following variables:

# iCloud Credentials (fallback if not in headers)
ICLOUD_EMAIL=your-email@icloud.com
ICLOUD_APP_SPECIFIC_PASSWORD=xxxx-xxxx-xxxx-xxxx

# iCloud Servers (optional, defaults to standard iCloud servers)
CALDAV_SERVER=https://caldav.icloud.com
CARDDAV_SERVER=https://contacts.icloud.com
IMAP_SERVER=imap.mail.me.com
SMTP_SERVER=smtp.mail.me.com

# Server Configuration
MCP_SERVER_PORT=8000
IMAP_PORT=993
SMTP_PORT=587

Authentication

The server supports two authentication methods (checked in order):

1. Request Headers (recommended for multi-user scenarios):

   • X-Apple-Email: iCloud email address

   • X-Apple-App-Specific-Password: App-specific password

2. Environment Variables (fallback):

   • ICLOUD_EMAIL

   • ICLOUD_APP_SPECIFIC_PASSWORD

If credentials are not found in either location, the server returns a 401 error.

Usage

Local Usage (stdio transport)

# Using Python directly
python run.py

# Or using the module
python -m icloud_mcp.server

Server Usage (Streamable HTTP transport)

# Using Python
python run.py --http --port 8000

# Using Docker Compose
docker-compose up

The server will be available at http://localhost:8000/mcp.

Integration with Claude Desktop

This method allows Claude Desktop to directly launch the MCP server as a subprocess.

Step 1: Install dependencies locally:

pip install -e .

Step 2: Create a .env file with your credentials:

cp .env.example .env
# Edit .env and add your iCloud credentials

Step 3: Find your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Step 4: Add this configuration (replace the path):

{
  "mcpServers": {
    "icloud": {
      "command": "python",
      "args": ["/absolute/path/to/icloud-mcp/run.py"],
      "network": {
        "enabled": true,
        "allowedDomains": [
          "caldav.icloud.com",
          "contacts.icloud.com",
          "*.contacts.icloud.com",
          "imap.mail.me.com",
          "smtp.mail.me.com"
        ]
      }
    }
  }
}

Important: Replace /absolute/path/to/icloud-mcp/ with the actual full path to your project directory.

Example on macOS:

{
  "mcpServers": {
    "icloud": {
      "command": "python",
      "args": ["/Users/username/Projects/icloud-mcp/run.py"],
      "network": {
        "enabled": true,
        "allowedDomains": [
          "caldav.icloud.com",
          "contacts.icloud.com",
          "*.contacts.icloud.com",
          "imap.mail.me.com",
          "smtp.mail.me.com"
        ]
      }
    }
  }
}

Note: The network.allowedDomains configuration is required for contacts to work properly, as the server needs to access iCloud's CardDAV servers.

Step 5: Restart Claude Desktop completely (Quit and reopen)

Verification

After restarting Claude Desktop:

1. Open Claude Desktop application

2. Look for the 🔨 (tools/hammer) icon in the bottom-right corner

3. You should see "icloud" server listed with green status

4. Try commands like:

   • "List my calendars"

   • "Show my contacts"

   • "Get my unread emails"

Troubleshooting

Server doesn't appear:

• Check JSON syntax in config file (use a JSON validator)

• View logs: Help → Show Logs in Claude Desktop

• Verify the path to run.py is absolute (not relative)

• Ensure Python is in your PATH

• Check that you're using Python 3.10-3.12 (not 3.13+)

401 Authentication errors:

• Ensure you're using an App-Specific Password, not your regular Apple password

• Generate one at: https://appleid.apple.com/account/manage

• Check .env file has correct credentials

Contacts not working (empty results or errors):

• Ensure you've added the network.allowedDomains configuration to Claude Desktop config

• The domains contacts.icloud.com and *.contacts.icloud.com must be in the allowed list

• Restart Claude Desktop after updating the config

Tools fail with 500 errors:

• Check server logs for details

• Verify iCloud credentials are valid

• Ensure network connectivity to iCloud servers

Architecture

Stateless Design

The server is fully stateless:

• No sessions or state stored between requests

• Each request contains all necessary authentication information

• Connections to iCloud services are created per-request and closed immediately

• Perfect for horizontal scaling and serverless deployments

Technical Implementation

• Transport: Streamable HTTP protocol with /mcp endpoint

• Calendar (CalDAV): Uses caldav library for standard CalDAV operations

• Contacts (CardDAV): Direct HTTP/WebDAV implementation using requests with proper RFC 6352 CardDAV protocol

• Email (IMAP/SMTP): Uses imapclient for IMAP and standard smtplib for SMTP

• Authentication: Headers via get_http_headers() with environment variable fallback

Security Considerations

• Always use HTTPS in production when using HTTP transport

• Store App-Specific Passwords securely (use secret management tools)

• Consider using header-based authentication for multi-user scenarios

• Never commit .env file to version control

• Network access is restricted to allowed iCloud domains only

Development

Project Structure

icloud-mcp/
├── src/
│   └── icloud_mcp/
│       ├── __init__.py
│       ├── config.py       # Configuration management
│       ├── auth.py         # Authentication handling
│       ├── calendar.py     # CalDAV tools
│       ├── contacts.py     # CardDAV tools (direct HTTP/WebDAV)
│       ├── email.py        # IMAP/SMTP tools
│       └── server.py       # FastMCP server and tool registration
├── .env.example            # Example environment configuration
├── .gitignore
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml          # Python project configuration and dependencies
├── run.py                  # Entry point script
└── README.md

Running Tests

# Install development dependencies
pip install -e ".[dev]"

# Run tests (when added)
pytest

Code Formatting

# Format code
black src/

# Lint code
ruff check src/

License

MIT License - See LICENSE file for details

Contributing

Contributions are welcome! Please:

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Submit a pull request

Support

For issues and questions:

• Open an issue on GitHub

• Check existing issues for solutions

• Review iCloud API documentation

Acknowledgments

Built with:

• FastMCP - MCP server framework

• caldav - CalDAV library for calendar operations

• requests - HTTP library for CardDAV operations

• IMAPClient - IMAP library

• vobject - vCard/iCalendar parsing