iCal MCP Server

A modern Model Context Protocol (MCP) server for managing iCalendar files. This server allows AI assistants to interact with calendar data through a standardized protocol.

Features

• Load calendars from:
  • Local files (.ics)
  • HTTP/HTTPS URLs
• Query events with filters for:
  • Date ranges
  • Search text (summary, description, location)
  • Location
  • Recurring event expansion
• Full CRUD operations:
  • Create new events
  • Update existing events
  • Delete events
• Multiple calendar support: Load and manage multiple calendars simultaneously
• Read-only mode: HTTP calendars are automatically read-only

Installation

Using npx (recommended)

You can run the server directly without installation:

npx @jonas/ical-mcp

Global Installation

npm install -g @jonas/ical-mcp
ical-mcp

Local Development

git clone https://github.com/jnss95/ical-mcp.git
cd ical-mcp
npm install
npm run build
npm start

Configuration

Environment Variables

Calendars are configured using environment variables at startup:

| Variable | Description | |----------|-------------| | CALENDAR_LINK | URL or path to a calendar (id defaults to "default") | | CALENDAR_LINK_{id} | URL or path to a calendar with custom id |

Examples:

Single calendar (id defaults to "default"):

CALENDAR_LINK=https://example.com/calendar.ics

Multiple calendars with custom IDs:

CALENDAR_LINK_work=https://example.com/work.ics
CALENDAR_LINK_personal=/path/to/personal.ics
CALENDAR_LINK_holidays=https://example.com/holidays.ics

VS Code MCP Configuration

Add to your VS Code settings (.vscode/mcp.json):

{
  "servers": {
    "ical": {
      "type": "stdio",
      "command": "npx",
      "args": ["@jnss95/ical-mcp"],
      "env": {
        "CALENDAR_LINK": "https://example.com/your-calendar.ics"
      }
    }
  }
}

With multiple calendars:

{
  "servers": {
    "ical": {
      "type": "stdio",
      "command": "npx",
      "args": ["@jnss95/ical-mcp"],
      "env": {
        "CALENDAR_LINK_work": "https://example.com/work.ics",
        "CALENDAR_LINK_personal": "/path/to/personal.ics"
      }
    }
  }
}

Claude Desktop Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "ical": {
      "command": "npx",
      "args": ["@jnss95/ical-mcp"],
      "env": {
        "CALENDAR_LINK": "https://example.com/your-calendar.ics"
      }
    }
  }
}

Available Tools

Calendar Management

| Tool | Description | |------|-------------| | list_calendars | List all loaded calendars | | get_calendar_info | Get metadata about a loaded calendar |

Event Operations

| Tool | Description | |------|-------------| | list_events | List all events in a calendar | | search_events | Search events with filters | | get_event | Get details of a specific event | | create_event | Create a new event | | update_event | Update an existing event | | delete_event | Delete an event |

Tool Examples

List Calendars

{
  "tool": "list_calendars",
  "arguments": {}
}

Search Events

{
  "tool": "search_events",
  "arguments": {
    "calendarId": "work",
    "startDate": "2024-01-01T00:00:00Z",
    "endDate": "2024-01-31T23:59:59Z",
    "searchText": "meeting",
    "expandRecurring": true
  }
}

Create Event

{
  "tool": "create_event",
  "arguments": {
    "calendarId": "work",
    "summary": "Team Meeting",
    "start": "2024-01-15T10:00:00Z",
    "end": "2024-01-15T11:00:00Z",
    "description": "Weekly team sync",
    "location": "Conference Room A"
  }
}

Create Recurring Event

{
  "tool": "create_event",
  "arguments": {
    "calendarId": "work",
    "summary": "Daily Standup",
    "start": "2024-01-15T09:00:00Z",
    "end": "2024-01-15T09:15:00Z",
    "rrule": "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR"
  }
}

Update Event

{
  "tool": "update_event",
  "arguments": {
    "calendarId": "work",
    "eventId": "[email protected]",
    "summary": "Updated Meeting Title",
    "location": "New Location"
  }
}

Development

Running Tests

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

Building

# Build TypeScript
npm run build

# Watch mode
npm run watch

Project Structure

ical_mcp/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── calendar/
│   │   ├── calendar.ts       # Calendar class (CRUD operations)
│   │   ├── loader.ts         # Calendar loading utilities
│   │   └── index.ts          # Module exports
│   └── types/
│       ├── calendar.ts       # Type definitions
│       ├── ical.d.ts         # ical.js type declarations
│       └── index.ts          # Type exports
├── build/                    # Compiled JavaScript
├── package.json
├── tsconfig.json
└── vitest.config.ts

License

MIT