Skip to content

README.md

Latest commit

 

History

History
188 lines (139 loc) · 6.18 KB

README.md

File metadata and controls

188 lines (139 loc) · 6.18 KB

MCP Fantastical Server

npm version CI License: MIT MCP

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):

  1. System Preferences → Privacy & Security → Calendars
  2. Grant "Full Calendar Access" to your terminal app or the process running the MCP server

Note: On macOS Sonoma and later, reading calendar events via AppleScript may fail with permission errors when running in subprocess contexts (e.g., MCP servers spawned by Claude). The native EventKit helper resolves this by using a different permission model.

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 (-1743) or timeouts when reading events

This occurs when the MCP server runs in a subprocess context (e.g., spawned by Claude Code or other MCP clients). macOS TCC permissions don't properly inherit through process chains.

Solutions:

  1. Recommended: The native EventKit helper (dist/native/fantastical-helper) handles this automatically. Rebuild with npm run build to compile it.
  2. Grant "Full Calendar Access" in System Settings → Privacy & Security → Calendars to the terminal app
  3. If running from source, ensure the Swift helper is compiled: npm run build:native

"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