Fantastical MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Fantastical MCP What's on my calendar today?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
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-mcpConfigure your MCP client to use uvx with fantastical-mcp as the argument.
Claude Desktop
Option 1: One-Click Install (Recommended)
Download the latest
.mcpbfile from the releases pageDouble-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_availabilityto 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 |
| All events for today, grouped by calendar |
| Events for the next N days, grouped by date |
| List all calendars with event counts |
| Full details for a specific event by ID |
| Full-text search across titles, locations, notes, attendees |
| Events from a specific calendar |
| Events in an arbitrary date window (past or future), optionally scoped to one calendar |
| Free/busy time slots for a date |
| Upcoming recurring events, optionally filtered by calendar |
| Pending event invitations that need a response |
| Most recently added or synced events |
| Structured JSON variant of |
| Structured JSON variant of |
| Structured JSON variant of |
| Create an event using natural language |
| 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
uvxInstall uv globally with Homebrew (
brew install uv)Alternative: Use the full path to
uvxin your config. Find it withwhich 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_CALENDARSto 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
opencommand.Read-only database access -- The database is opened in
?mode=roto prevent any risk of corruption.Blob format dependency -- The
NSKeyedArchiverserialisation 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
Available Tools
16 toolscreate_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
startandendas "YYYY-MM-DD".endis 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
Scored across 16 tools
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.
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.
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.
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
Related MCP Connectors
Connects ChatGPT to your Apple Calendar via a local Mac agent + Vercel relay
Mac & Windows: let ChatGPT, Claude & Cursor use your email, calendar, iMessage, Teams, files.
Calendar API for AI agents: events, availability, Google/Microsoft setup, scheduling, and iCal.
Let your AI agent read and act on your Mail, Calendar, Contacts and more. Works with iCloud.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables natural language calendar management through Fantastical on macOS, allowing users to create events, view schedules, search appointments, and navigate their calendar without leaving their AI conversation.320 npm18MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to access and interact with macOS Calendar.app events and reminders, including viewing, searching, and filtering calendar data.19 PyPI2MIT
- AlicenseAqualityDmaintenanceEnables querying and managing Fantastical calendars and events via the MCP protocol, allowing AI assistants to list calendars, create events using natural language, and search or retrieve event details.65MIT
- AlicenseAqualityDmaintenanceEnables read/write access to Apple Calendar on macOS by bypassing permission restrictions via JXA scripts, allowing users to manage calendar events through natural language.3MIT