fantastical
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 show my events for this week"
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
A CLI and MCP server for Fantastical on macOS.
Fantastical keeps its own calendar store that is invisible to Calendar.app and EventKit. This tool bridges the gap by talking to Fantastical directly — via JXA scripting, Apple Shortcuts, and URL schemes — so you can query and create events from the terminal or from any MCP-compatible AI assistant.
Requirements
macOS with Fantastical installed
Python 3.10+
Related MCP server: MCP Fantastical Server
Install
git clone git@github.com:ramm/fantastical-mcp.git
cd fantastical-mcp
uv syncmacOS permissions
On first run, macOS will prompt you to grant permissions. Click Allow when asked:
Automation: your terminal app (Terminal, iTerm, etc.) needs permission to control Fantastical via Apple Events. Triggered by commands like
calendars.Shortcuts: running shortcuts from the terminal may prompt you to allow your terminal to run shortcuts. Triggered by commands like
eventsandsearch.
These prompts only appear once. If you accidentally deny a permission, you can re-enable it in System Settings > Privacy & Security > Automation (or Shortcuts).
When using the MCP server, the prompts will appear for the MCP host app (e.g. Claude Desktop) instead of your terminal.
Quick start
# List your calendars (works immediately, no setup needed)
uv run fantastical calendars
# Create an event using natural language
uv run fantastical add "Lunch with Alex tomorrow at noon"
# Set up helper shortcuts (one-time, needed for events/search)
uv run fantastical setup
# After setup — list today's events
uv run fantastical events today
# Upcoming events for the next 7 days
uv run fantastical events upcoming
# Search events by title
uv run fantastical search "standup"All commands support --json for machine-readable output:
uv run fantastical --json events todaySetup
Some features (events by date, search) use Fantastical's App Intents through Apple Shortcuts. Run the guided setup to create the required shortcuts:
uv run fantastical setupThis checks which helper shortcuts are installed and gives step-by-step instructions for any that are missing. You only need to do this once.
Feature | Needs setup? |
List calendars | No |
Create event | No |
Events by date | Yes |
Search events | Yes |
MCP server
To use fantastical-cli as an MCP server (e.g. with Claude Desktop), start it in stdio mode:
uv run fantastical serveOr add it to your MCP client config:
{
"mcpServers": {
"fantastical": {
"command": "uv",
"args": ["run", "--directory", "/path/to/fantastical-cli", "fantastical", "serve"]
}
}
}The server exposes these tools:
Tool | Description | Response format |
| List all calendars | Plain text, one per line |
| Events in a date range | Compact tab-separated (id, title, start, end, attendeeCount) |
| Search events by title | Same as |
| Create event via natural language | JSON |
| Full details of a cached event | Key-value text with attendees |
| Clear in-memory event/attendee caches | Status message |
List and search results are cached in memory — use get_event_details to retrieve full data (calendar, URL, attendees) for a specific event.
CLI reference
Command | Description |
| List all Fantastical calendars |
| Create event via natural language |
| Today's events |
| Next 7 days (configurable with |
| Events in a date range ( |
| Filter by calendar name |
| Search events by title |
| Create/update helper shortcuts |
| Remove helper shortcuts |
| Start MCP server (stdio) |
Uninstall shortcuts
macOS doesn't support programmatic shortcut deletion. The uninstall command opens each helper shortcut in Shortcuts.app for you to delete manually:
uv run fantastical uninstallAuthorship
This project was created by autonomous AI software engineering agents and explicitly reviewed and approved by a human.
License
Available Tools
6 toolsclear_cacheA
Clear the in-memory event and attendee caches.
Use when starting a fresh analysis session.
Inputs: no named parameters. Returns: result
create_eventA
Create event using natural language (e.g. 'Meeting tomorrow at 3pm').
Inputs: sentence (required), notes, calendar. Returns: result
get_event_detailsA
Get full details of a cached event by ID.
Returns all fields: title, startDate, endDate, calendar, fantasticalURL, calendarName. Events are cached from previous list_events/search_events calls. Attendees are fetched lazily on first request and cached for the session.
Inputs: event_id (required). Returns: result
list_calendarsA
List all Fantastical calendars.
Fast and lightweight — no shortcuts required, uses JXA directly. Returns plain text: one calendar per line as "name (id)".
Inputs: no named parameters. Returns: result
list_eventsA
List calendar events in a date range (YYYY-MM-DD).
Accepts 'today', 'tomorrow', 'yesterday', or YYYY-MM-DD. Defaults to today only. Start with 2-week chunks. If results are sparse, increase to months or more.
Returns compact tab-separated output: id, title, startDate, endDate, attendeeCount. All events are cached — use get_event_details for full data (calendar, URL, etc.). Can be called in parallel for different date ranges.
Inputs: to_date, calendar, from_date. Returns: result
search_eventsA
Search events by title.
Default search window is ±30 days. Override with from_date/to_date (YYYY-MM-DD). Start with 2-week chunks. If results are sparse, increase to months or more. Same compact tab-separated output as list_events with caching. Can be called in parallel for different queries.
Inputs: query (required), to_date, from_date. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool serves a distinct purpose: cache management, event creation, event detail retrieval, calendar listing, event listing by date, and event search by title. No two tools have overlapping functionality.
All tool names follow a consistent verb_noun pattern using lowercase and underscores (e.g., list_calendars, search_events), making them predictable and easy to distinguish.
With 6 tools, the set is well-scoped for a calendar event server. Each tool has a clear role, and the count is within the ideal 3-15 range.
The toolset covers event creation and read operations (list, search, get details) and calendar listing, but lacks update and delete functionality for events, and calendar management beyond listing. These are notable gaps for a calendar application.
Maintenance
Related MCP Connectors
Calendar API for AI agents: events, availability, Google/Microsoft setup, scheduling, and iCal.
AI-native scheduling: check availability, book meetings, cancel and reschedule via MCP
Manage Superlist tasks and lists in plain language from any MCP-compatible AI agent.
Official Akiflow MCP for tasks, calendars, scheduling, time slots, and meeting transcripts.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceTransforms macOS calendar management into a conversational experience using natural language, allowing users to create, manage, and update calendar events seamlessly through an MCP-compatible client.333MIT
- 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
- AlicenseAqualityDmaintenanceEnables AI assistants to read and create Fantastical calendar events on macOS using local database access and URL schemes, working entirely offline without API keys or network access.167MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients to interact with Apple Calendar locally on macOS through EventKit, including listing calendars and events, creating events, and updating events with privacy-conscious safeguards.MIT