Skip to main content
Glama
Fantastical MCP

Fantastical MCP

by jaydenk

Fantastical MCP

Publish to PyPI

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

Related MCP server: calendar-app-mcp

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

  1. Download the latest .mcpb file from the releases page

  2. Double-click the file

  3. Done!

Option 2: Manual Config

  1. Go to Claude → Settings → Developer → Edit Config

  2. Add the Fantastical server:

{
  "mcpServers": {
    "fantastical": {
      "command": "uvx",
      "args": ["fantastical-mcp"]
    }
  }
}
  1. 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:

  1. Make sure Fantastical is installed and has been opened at least once

    • The Fantastical database needs to exist for the server to read events

  2. 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)

  3. "Database not found" errors

    • Fantastical stores its database at ~/Library/Group Containers/group.com.flexibits.fantastical2.mac/. Ensure this path exists and is accessible.

  4. 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

Licence

MIT

Available Tools

16 tools
create_eventA

Create a new event in Fantastical using natural language.

Fantastical's parser handles dates, times, locations, and recurrence naturally. Examples: "Lunch with Sara tomorrow at noon at The Crafers Hotel", "Weekly team standup every Monday at 9am".

Args: sentence: Natural language event description. calendar: Optional calendar name to create the event in. add_immediately: If True, add without showing confirmation UI (default False).

Inputs: sentence (required), calendar, add_immediately. Returns: result

get_availabilityA

Show free/busy time slots for a specific date.

Args: date: Date in YYYY-MM-DD format. calendars: Optional list of calendar names to check. If omitted, checks all calendars.

Inputs: date (required), calendars. Returns: result

get_calendarsA

List all calendars with their event counts.

Inputs: no named parameters. Returns: result

get_eventA

Get full details for a specific event by its ID.

Args: event_id: The event ID (shown in parentheses in event listings).

Inputs: event_id (required). Returns: result

get_event_jsonA

Machine-readable variant of get_event. Returns None-valued fields when a value is absent rather than omitting them, so clients can treat the shape as stable.

Args: event_id: The event rowid (as returned by get_today_json etc.).

Inputs: event_id (required). Returns: object

get_events_by_calendarA

Get events from a specific calendar.

Args: calendar: Calendar name (e.g. "Work", "Personal"). Use get_calendars to see available names. days: Number of days to look ahead (default 30).

Inputs: calendar (required), days. Returns: result

get_events_in_rangeA

Get events in an arbitrary date window (past or future), grouped by date.

Specify the window in exactly ONE of two ways (not both):

  • Absolute: pass both start and end as "YYYY-MM-DD". end is inclusive of the whole day (e.g. start="2026-05-28", end="2026-06-10" covers all of the 10th).

  • Relative: pass days_back (a positive integer) for events from that many days ago through the end of today.

Args: calendar: Optional calendar name to scope to (use get_calendars for names). Omit to query all calendars — note that an event mirrored across several calendars then appears once per calendar; scope to a single calendar to get a clean, duplicate-free list. start: Absolute-mode start date, "YYYY-MM-DD". end: Absolute-mode end date, "YYYY-MM-DD" (inclusive). days_back: Relative-mode window size in days.

Inputs: calendar, start, end, days_back. Returns: result

get_invitationsB

List pending event invitations that need a response.

Args: limit: Maximum number of results (default 20).

Inputs: limit. Returns: result

get_recentA

Show the most recently added or synced calendar events.

Useful for seeing what's new on the calendar without knowing specific dates.

Args: limit: Maximum number of results (default 10).

Inputs: limit. Returns: result

get_recurringA

List upcoming recurring events, optionally filtered by calendar.

Useful for understanding the regular schedule (standups, focus blocks, etc.).

Args: calendar: Optional calendar name to filter by. Use get_calendars to see available names. limit: Maximum number of results (default 50).

Inputs: calendar, limit. Returns: result

get_todayA

Get all calendar events for today, grouped by calendar.

Inputs: no named parameters. Returns: result

get_today_jsonA

Machine-readable variant of get_today.

Returns today's events as a structured dict so programmatic clients (dashboards, automations) don't have to parse the pretty-printed text output. Event times are ISO-8601 strings in the event's original timezone.

Response shape::

{
  "now": ISO-8601 string (current local time),
  "timezone": IANA name (e.g. "Australia/Adelaide"),
  "events": [{id, title, calendar, start, end, all_day,
              location, recurring, attendees_count}, ...]
}

Inputs: no named parameters. Returns: object

get_upcomingB

Get calendar events for the next N days, grouped by date.

Args: days: Number of days to look ahead (default 7).

Inputs: days. Returns: result

get_upcoming_jsonA

Machine-readable variant of get_upcoming.

Args: days: Number of days to look ahead (default 7).

Response shape mirrors get_today_json but covers the next days days.

Inputs: days. Returns: object

search_eventsB

Search events by title, location, notes, or attendees.

Args: query: Search term (supports FTS5 syntax: AND, OR, NOT, quotes for phrases). limit: Maximum number of results (default 20).

Inputs: query (required), limit. Returns: result

show_dateA

Open Fantastical's mini calendar to a specific date.

Args: date: Date in YYYY-MM-DD format.

Inputs: date (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 16 tools

    Disambiguation4/5

    Tools are largely distinct, but some overlap exists between get_today, get_upcoming, get_events_in_range, and get_recent, which all retrieve events over different time windows. Descriptions help distinguish them, but an agent might occasionally select the wrong one.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern using snake_case (e.g., create_event, get_calendars, search_events). The pattern is predictable and easy to understand.

    Tool Count4/5

    16 tools is slightly on the high side for a calendar server, but each tool addresses a specific query need (today, upcoming, range, recurring, etc.). The JSON variants could be merged, but overall the count is still reasonable.

    Completeness2/5

    The tool surface is heavily read-oriented. While create_event is present, there are no tools for updating or deleting events, nor for responding to invitations. This leaves significant gaps in event lifecycle management.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers