fantastical

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

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