mcp-fantastical

This MCP server enables natural language and calendar-aware interactions with Fantastical from conversational interfaces. It exposes tools that let you create events from natural language, view today’s and upcoming events, open Fantastical to a specific date, list calendars, and search for events by query. Core capabilities include fantasical_create_event for natural language event creation, fantasical_get_today to fetch today’s events, fantasical_get_upcoming to retrieve future events for a specified window, fantasical_show_date to jump to a date in Fantastical, fantasical_get_calendars to list calendars, and fantasical_search to query events by title, location, or notes. Use these tools by invoking the MCP server in your Claude/Code environment, or directly via npx as shown in installation instructions.

Prerequisites:

• macOS (Fantastical is macOS-only)
• Node.js 18+ and npm
• Fantastical installed
• Calendar access permissions for Terminal/Claude

Installation steps:

1. Install or run via npx (Recommended):

npx mcp-fantastical

2. From source (clone and build):

git clone https://github.com/aplaceforallmystuff/mcp-fantastical.git
cd mcp-fantastical
npm install
npm run build

3. Run locally (after build):

node dist/index.js

Configuration for Claude (examples):

• Claude Desktop:

{
  "mcpServers": {
    "fantastical": {
      "command": "npx",
      "args": ["-y", "mcp-fantastical"]
    }
  }
}

• Claude Code (user settings):

{
  "mcpServers": {
    "fantastical": {
      "command": "npx",
      "args": ["-y", "mcp-fantastical"]
    }
  }
}

Notes and tips:

• This server uses AppleScript to communicate with Fantastical and the Calendar app. On macOS Sonoma and newer, permission prompts may occur; ensure Accessibility and Full Calendar Access are granted to the Terminal or process running the MCP server.
• If you encounter calendar reading issues in subprocess contexts, rebuild to ensure the native EventKit helper is compiled: npm run build.
• The server requires macOS due to Fantastical dependencies; it will not run on Windows or Linux.
• If Fantastical is not opening or URL schemes are disabled, ensure Fantastical is installed and open, and that URL schemes are enabled in preferences.