Fantastical MCP

An MCP server that gives AI assistants read/write access to your Fantastical calendar on macOS.

What it does

fantastical-mcp reads calendar events directly from Fantastical's local SQLite database and creates events via Fantastical's x-fantastical3:// URL scheme. No TCC permissions, no API keys, no network access -- it works entirely offline using the data Fantastical already stores on your Mac.

Read -- Query events by date range, calendar, or full-text search
Recurring events -- Series are expanded into per-occurrence results with timezone-aware rule evaluation and de-duplication of moved occurrences
Write -- Create events using Fantastical's natural language parser
Navigate -- Open Fantastical to a specific date

Installation

Prerequisites

macOS
Fantastical installed with at least one calendar
An MCP client, such as Claude Desktop or Claude Code
uv Python package manager: brew install uv

Install via uvx (Any MCP Client)

Fantastical MCP is published on PyPI and can be run directly with uvx:

uvx fantastical-mcp

Configure your MCP client to use uvx with fantastical-mcp as the argument.

Claude Desktop

Option 1: One-Click Install (Recommended)

Download the latest .mcpb file from the releases page
Double-click the file
Done!

Option 2: Manual Config

Go to Claude → Settings → Developer → Edit Config
Add the Fantastical server:

{
  "mcpServers": {
    "fantastical": {
      "command": "uvx",
      "args": ["fantastical-mcp"]
    }
  }
}

Save and restart Claude Desktop

Claude Code

claude mcp add-json fantastical '{"command":"uvx","args":["fantastical-mcp"]}'

To make it available globally (across all projects), add -s user:

claude mcp add-json -s user fantastical '{"command":"uvx","args":["fantastical-mcp"]}'

Verify it's working

After installation:

If using Claude Desktop, you should see "Fantastical MCP" in the "Search and tools" list
Try asking: "What's on my calendar today?"

Sample Usage

"What's on my calendar today?"
"Do I have any meetings on Thursday?"
"Create a lunch meeting with Sarah tomorrow at noon at The Italian Place"
"When am I free this Wednesday afternoon?"
"Show me all events from my Work calendar this week"
"Do I have any pending event invitations?"

Tips

Create a project in Claude with custom instructions that explain how you organise your calendars. Tell Claude which calendars to prioritise and how you like events formatted.
Pair with a task management MCP server (like things-mcp) so Claude can cross-reference your tasks and calendar, block time for deep work, or create todos from upcoming meetings.
Use get_availability to quickly find free slots: "When am I free for a 90-minute block this week?"

Local Development

git clone https://github.com/jaydenk/fantastical-mcp.git
cd fantastical-mcp
uv venv && uv pip install -e ".[test]"

See docs/configuration.md for environment variables, calendar exclusion, and transport options.

Available tools

Tool	Description
`get_today`	All events for today, grouped by calendar
`get_upcoming`	Events for the next N days, grouped by date
`get_calendars`	List all calendars with event counts
`get_event`	Full details for a specific event by ID
`search_events`	Full-text search across titles, locations, notes, attendees
`get_events_by_calendar`	Events from a specific calendar
`get_events_in_range`	Events in an arbitrary date window (past or future), optionally scoped to one calendar
`get_availability`	Free/busy time slots for a date
`get_recurring`	Upcoming recurring events, optionally filtered by calendar
`get_invitations`	Pending event invitations that need a response
`get_recent`	Most recently added or synced events
`get_today_json`	Structured JSON variant of `get_today` for programmatic clients
`get_upcoming_json`	Structured JSON variant of `get_upcoming`
`get_event_json`	Structured JSON variant of `get_event`
`create_event`	Create an event using natural language
`show_date`	Open Fantastical's mini calendar to a date

See docs/tools.md for parameters, types, defaults, and example output.

Troubleshooting

If it's not working:

Make sure Fantastical is installed and has been opened at least once
- The Fantastical database needs to exist for the server to read events
Claude Desktop can't find uvx
- Install uv globally with Homebrew (brew install uv)
- Alternative: Use the full path to uvx in your config. Find it with which uvx (typically /Users/USERNAME/.local/bin/uvx)
"Database not found" errors
- Fantastical stores its database at ~/Library/Group Containers/group.com.flexibits.fantastical2.mac/. Ensure this path exists and is accessible.
System calendars cluttering results
- Set FANTASTICAL_EXCLUDED_CALENDARS to hide calendars like Weather or Openings. See docs/configuration.md for details.

Limitations

No update or delete -- Fantastical's URL scheme only supports event creation. Modification and deletion require EventKit, which needs TCC permissions.
macOS only -- Relies on Fantastical's macOS database location and the open command.
Read-only database access -- The database is opened in ?mode=ro to prevent any risk of corruption.
Blob format dependency -- The NSKeyedArchiver serialisation format is an internal detail of Fantastical and could change between versions. An FTS fallback path mitigates this.

Documentation

Tool reference -- Detailed parameters and example output for every tool
Configuration guide -- Environment variables, transport options, calendar exclusion
How it works -- Technical architecture and design decisions
Development guide -- Project structure, testing, and contributing

Licence

MIT