Skip to main content
Glama
jnss95

iCal MCP Server

by jnss95
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

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

Related MCP server: Google Calendar MCP Server

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": "event-uid@example.com",
    "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

Install Server
A
license - permissive license
A
quality
D
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

Related MCP Servers

View all related MCP servers

Related MCP Connectors

  • Chronary

    Calendar API for AI agents: events, availability, Google/Microsoft setup, scheduling, and iCal.

  • calendar-bridge

    Connects ChatGPT to your Apple Calendar via a local Mac agent + Vercel relay

  • CalendarMCP

    Hosted Google Calendar MCP server for AI agents. No self-hosting or Google Cloud setup.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jnss95/ical-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server