mcp-ical

The mcp-ical MCP server provides natural language calendar management for macOS. It enables you to create, update, and query calendar events using conversational prompts. The server is designed to work with MCP-compatible clients (such as Claude for Desktop) and can leverage your existing calendars (including Google via iCloud integration when configured) to add or modify events using natural language. Typical interactions include asking about your schedule, creating events with location and notes, and adjusting times, dates, reminders, or calendar assignments through simple commands.

To use it, configure your MCP client to point at the mcp-ical server, then issue natural language requests like “Schedule a lunch meeting tomorrow at noon” or “What’s on my calendar for next week?” The server will interpret the intent, map it to calendar actions, and respond with confirmations or results. It supports features such as custom calendar selection, location and notes, smart reminders, recurring events, event updates, and multi-calendar management, including Google Calendar integration when set up via iCloud.

Prerequisites:

• uv package manager installed and available in your PATH
• macOS with Calendar app configured
• An MCP client (e.g., Claude for Desktop) to connect to the MCP server

Installation steps:

1. Clone the repository and set up the project

# Clone the repository
git clone https://github.com/Omar-V2/mcp-ical.git
cd mcp-ical

2. Install or sync dependencies with uv

uv sync

3. Configure Claude for Desktop to point to the MCP server Create or edit the Claude desktop config file at: ~/Library/Application Support/Claude/claude_desktop_config.json with the following content:

{
  "mcpServers": {
    "mcp-ical": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-ical",
        "run",
        "mcp-ical"
      ]
    }
  }
}

4. Launch Claude for Calendar Access

Important: Claude must be launched from the terminal to properly request calendar permissions.

/Applications/Claude.app/Contents/MacOS/Claude

5. Start using the MCP server In Claude, try a sample prompt like:

What's my schedule looking like for next week?

Notes:

• If you encounter calendar access prompts, ensure Claude was started from the terminal as shown above.
• You can customize the directory path in the config to the absolute path of your mcp-ical folder.

Tips and considerations:

• This MCP server relies on uv for orchestration; use an absolute path in the integration config.
• Ensure Claude (or your chosen MCP client) is launched from the terminal to grant macOS Calendar permissions when prompted.
• If you need Google Calendar integration, ensure your calendars are synced with iCloud and specify the target Google calendar when creating/updating events.
• Known issues include occasional misinterpretation of non-standard recurring schedules; test complex recurrences and adjust prompts accordingly.
• You can update events, move events between calendars, update locations, notes, reminders, and adjust recurring patterns through natural language commands.