Skip to main content
Glama

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+

  • uv

Related MCP server: MCP Fantastical Server

Install

git clone git@github.com:ramm/fantastical-mcp.git
cd fantastical-mcp
uv sync

macOS 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 events and search.

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 today

Setup

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 setup

This 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 serve

Or 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_calendars

List all calendars

Plain text, one per line

list_events

Events in a date range

Compact tab-separated (id, title, start, end, attendeeCount)

search_events

Search events by title

Same as list_events

create_event

Create event via natural language

JSON

get_event_details

Full details of a cached event

Key-value text with attendees

clear_cache

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

calendars

List all Fantastical calendars

add "..."

Create event via natural language

events today

Today's events

events upcoming

Next 7 days (configurable with --days)

events list

Events in a date range (--from, --to)

events --calendar "X"

Filter by calendar name

search <query>

Search events by title

setup [--force]

Create/update helper shortcuts

uninstall

Remove helper shortcuts

serve

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 uninstall

Authorship

This project was created by autonomous AI software engineering agents and explicitly reviewed and approved by a human.

License

MIT

Available Tools

6 tools
clear_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

    A4.1/5.0

    Scored across 6 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Transforms 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.
      333
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables 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.
      16
      7
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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