MCP Fantastical Server

MCP server for Fantastical - the powerful calendar app for macOS.

Why Use This?

• Natural language event creation - Use Fantastical's powerful natural language parsing ("Meeting with John tomorrow at 3pm")
• View your schedule - Check today's events or upcoming appointments without leaving your conversation
• Quick calendar access - Jump to any date in Fantastical instantly
• Calendar-aware AI - Let Claude understand your availability and schedule context
• Zero configuration - Works with your existing Fantastical and Calendar setup

Features

| Category | Capabilities | |----------|-------------| | Event Creation | Create events using natural language, specify calendar, add notes | | Schedule Viewing | View today's events, upcoming events for any number of days | | Navigation | Open Fantastical to specific dates | | Search | Search events by title, location, or notes | | Calendar Management | List all available calendars |

Prerequisites

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

Installation

Using npm (Recommended)

npx mcp-fantastical

From Source

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

Configuration

No API keys required - this server uses AppleScript to communicate with Fantastical and the Calendar app.

For Claude Desktop

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

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

For Claude Code

Add to ~/.claude.json:

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

Permissions

On first run, you may need to grant the following permissions:

Accessibility (for event creation via URL scheme):

1. System Preferences → Privacy & Security → Accessibility
2. Add Terminal (or your terminal app) to the allowed list

Full Calendar Access (for reading events):

The native helper ships as an ad-hoc-signed .app bundle (FantasticalHelper.app). The first time the MCP server reads calendar data, macOS will show a one-time prompt attributed to "FantasticalHelper" asking to grant Full Calendar Access. Approve it.

If you miss the prompt or need to re-grant later:

1. System Settings → Privacy & Security → Calendars
2. Enable FantasticalHelper

Note: Prior versions shipped a raw helper binary, which macOS couldn't attribute a TCC permission to when launched under Claude Desktop — the prompt never appeared and access was silently denied (#6). The bundled + signed helper fixes this.

Usage Examples

Creating Events

• "Schedule a meeting with the team tomorrow at 2pm"
• "Add dentist appointment Friday at 10am to my Personal calendar"
• "Create a recurring standup every Monday at 9am"
• "Block off next Tuesday afternoon for deep work"

Viewing Schedule

• "What's on my calendar today?"
• "Show me my schedule for the next week"
• "What meetings do I have tomorrow?"
• "Am I free on Friday afternoon?"

Navigation

• "Open my calendar to next Monday"
• "Show me December 25th in Fantastical"
• "Jump to next week in my calendar"

Searching

• "Find all meetings with Sarah"
• "Search for dentist appointments"
• "Look up project review meetings"

Available Tools

| Tool | Description | |------|-------------| | fantastical_create_event | Create an event using natural language parsing | | fantastical_get_today | Get today's calendar events | | fantastical_get_upcoming | Get upcoming events for specified number of days | | fantastical_show_date | Open Fantastical to a specific date | | fantastical_get_calendars | List all available calendars | | fantastical_search | Search for events by query |

Development

# Watch mode for development
npm run watch

# Build TypeScript
npm run build

# Run locally
node dist/index.js

Troubleshooting

"AppleScript error: Not authorized to send Apple events"

Grant accessibility permissions:

1. Open System Preferences → Privacy & Security → Accessibility
2. Click the lock to make changes
3. Add Terminal (or your terminal app) and enable it

Calendar permission errors, or "Calendar access denied" under Claude Desktop

macOS TCC permissions don't inherit through the Claude Desktop → npx → node → helper chain. The native helper is wrapped in an ad-hoc-signed FantasticalHelper.app bundle so macOS has a stable code identity to attribute the calendar permission to.

Solutions:

1. Look for a one-time system prompt attributed to FantasticalHelper and approve it. If it appeared behind another window, restart your MCP client and retry.
2. Check System Settings → Privacy & Security → Calendars and enable FantasticalHelper.
3. If running from source, rebuild the bundle: npm run build:native.
4. If the bundle is missing a code signature for any reason, re-sign it: codesign --force --sign - dist/native/FantasticalHelper.app.

"Error: This MCP server only works on macOS"

This server requires macOS because Fantastical is a macOS application. It uses AppleScript to communicate with Fantastical and the Calendar app.

Events not showing up

• Ensure Fantastical is syncing with iCloud/Calendar
• Check that Calendar.app has access to the same calendars
• Verify the event was created in the correct calendar
• Grant Full Calendar Access (see above)

Fantastical not opening

• Ensure Fantastical is installed
• Try opening Fantastical manually first
• Check that URL schemes are enabled in Fantastical preferences

License

MIT - see LICENSE for details.

Links

• Fantastical - Official Fantastical website
• Model Context Protocol - MCP specification
• GitHub Repository