Calendar MCP Server

MCP (Model Context Protocol) server for calendar management via Claude Code. Uses iCalendar format (RFC 5545) for data storage.

Features

• 6 Calendar Tools: Create, list, update, delete, find free time, and search events
• Natural Language Dates: Supports inputs like "tomorrow at 2pm" or "next Tuesday"
• iCalendar Format: Standard .ics format for portability
• Git Integration: Automatic commits for change tracking
• Multi-Device Support: Configure per-device vault paths

Installation

npm install
npm run build

Configuration

Add to your Claude Code MCP settings (~/.claude/settings.json):

{
  "mcpServers": {
    "calendar": {
      "command": "node",
      "args": ["/path/to/calendar-mcp/dist/index.js"],
      "env": {
        "VAULT_PATH": "/path/to/your/obsidian-vault"
      }
    }
  }
}

The server creates and manages a Calendar/events.ics file within your vault.

Tools

calendar_create_event

Create a new calendar event.

Parameters:
- title (required): Event title
- start (required): Start date/time (ISO 8601 or natural language)
- end: End date/time (defaults to start + 1 hour)
- location: Event location
- description: Event description
- allDay: Whether this is an all-day event

calendar_list_events

List calendar events with optional filtering.

Parameters:
- startDate: Filter events after this date
- endDate: Filter events before this date
- limit: Maximum events to return (default: 50)
- sortOrder: 'asc' or 'desc' (default: 'asc')

calendar_update_event

Update an existing event.

Parameters:
- id (required): Event ID to update
- title: New title
- start: New start date/time
- end: New end date/time
- location: New location
- description: New description

calendar_delete_event

Delete an event by ID.

Parameters:
- id (required): Event ID to delete

calendar_find_free_time

Find available time slots.

Parameters:
- duration (required): Duration in minutes
- startDate (required): Start of search range
- endDate (required): End of search range
- workingHoursOnly: Only 9am-5pm (default: true)
- maxResults: Maximum slots to return (default: 5)

calendar_search_events

Search for events by text or criteria.

Parameters:
- query: Search text (searches title, description, location)
- startDate: Filter after this date
- endDate: Filter before this date
- location: Filter by location
- limit: Maximum results (default: 20)

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Watch mode for development
npm run dev

Data Format

Calendar data is stored in standard iCalendar format:

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Calendar MCP//EN
BEGIN:VEVENT
UID:[email protected]
DTSTAMP:20250125T120000Z
DTSTART:20250125T140000Z
DTEND:20250125T150000Z
SUMMARY:Event Title
LOCATION:Event Location
DESCRIPTION:Event Description
STATUS:CONFIRMED
END:VEVENT
END:VCALENDAR

License

MIT