MCP Calendar Server

A production-quality Model Context Protocol (MCP) server for calendar management with robust timezone handling, recurrence support, and idempotency guarantees.

🎯 What is MCP?

The Model Context Protocol is a standardized way for AI agents (like Claude, ChatGPT, etc.) to interact with external tools and data sources. This server exposes calendar operations as MCP tools, allowing AI assistants to:

• Create events with timezone-aware scheduling
• List events with automatic recurrence expansion
• Cancel individual instances or entire event series

✨ Features

🌍 Timezone Correctness (Top Priority)

Timezone handling is notoriously difficult. Here's how we handle it:

• Storage: All events stored in UTC (source of truth)
• Input: Accept ISO 8601 datetime + IANA timezone (e.g., "Asia/Kolkata")
• Output: Return events in their original timezone
• DST Handling: Recurrence expansion happens in local time to preserve wall-clock semantics (e.g., "9 AM daily" stays at 9 AM even across DST transitions)
• Library: Uses Luxon for robust timezone math

Why UTC Storage?

• Single source of truth
• No ambiguity during DST transitions
• Easy comparison and sorting
• Portable across systems

Why Original Timezone Matters?

• Preserves user intent ("9 AM in Kolkata" not "3:30 AM UTC")
• Correct recurrence expansion (daily meetings stay at same wall time)

🔁 Recurrence Support

Supports repeating events with:

• Frequencies: daily, weekly, monthly
• Intervals: Every N days/weeks/months (e.g., "every 2 weeks")
• End Dates: until parameter (ISO 8601)

Implementation Design:

• Recurrence rules stored as JSON in the database
• Virtual instances generated on-demand during calendar.list
• No duplicate rows for recurring events
• Cancel individual instances via cancellations table
• Safety limits: Max 1000 instances per query to prevent DOS

🔒 Idempotency

Prevents duplicate events from retries:

• Optional idempotency_key parameter in calendar.create
• If key exists, returns existing event (no duplicate created)
• Unique constraint enforced at database level

💾 Storage

Uses SQLite with better-sqlite3:

• Synchronous API: Simpler, more reliable than async
• WAL Mode: Better concurrency
• Schema:
  • events: Core event data (title, start_utc, duration, timezone, recurrence)
  • cancellations: Tracks cancelled instances of recurring events
  • Indexes on start_utc and idempotency_key for performance

📦 Installation

# Clone or navigate to project directory
cd calender-mcp

# Install dependencies
npm install

# Build TypeScript
npm run build

🚀 Usage

Running the Server

npm start

The server runs on stdio (standard input/output) as per MCP specification.

Configuring with Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "calendar": {
      "command": "node",
      "args": ["C:/path/to/calender-mcp/dist/index.js"]
    }
  }
}

Example Tool Calls

1. Create a Simple Event

{
  "tool": "calendar.create",
  "arguments": {
    "title": "Team Standup",
    "start": "2026-01-20T09:00:00",
    "end": "2026-01-20T09:30:00",
    "tz": "Asia/Kolkata"
  }
}

2. Create a Recurring Event

{
  "tool": "calendar.create",
  "arguments": {
    "title": "Weekly Review",
    "start": "2026-01-20T15:00:00",
    "end": "2026-01-20T16:00:00",
    "tz": "America/New_York",
    "recurrence": {
      "freq": "weekly",
      "interval": 1,
      "until": "2026-06-30T23:59:59"
    },
    "idempotency_key": "weekly-review-2026"
  }
}

3. List Events

{
  "tool": "calendar.list",
  "arguments": {
    "range_start": "2026-01-20T00:00:00Z",
    "range_end": "2026-01-27T00:00:00Z"
  }
}

4. Cancel an Entire Event Series

{
  "tool": "calendar.cancel",
  "arguments": {
    "event_id": "abc-123-def-456"
  }
}

5. Cancel a Specific Instance

{
  "tool": "calendar.cancel",
  "arguments": {
    "event_id": "abc-123-def-456",
    "instance_start_utc": "2026-01-27T10:00:00.000Z"
  }
}

🏗️ Architecture

src/
├── index.ts              # MCP server setup & tool registration
├── storage/
│   └── db.ts            # SQLite schema & connection
├── time/
│   └── timezone.ts      # UTC conversion utilities (Luxon)
├── recurrence/
│   └── expand.ts        # Recurrence expansion logic
└── tools/
    ├── create.ts        # calendar.create handler
    ├── list.ts          # calendar.list handler
    └── cancel.ts        # calendar.cancel handler

🧪 Testing

Create a test script (test.mjs):

import { spawn } from 'child_process';

const server = spawn('node', ['dist/index.js']);

// Send MCP request
const request = {
  jsonrpc: '2.0',
  id: 1,
  method: 'tools/call',
  params: {
    name: 'calendar.create',
    arguments: {
      title: 'Test Event',
      start: '2026-01-20T10:00:00',
      end: '2026-01-20T11:00:00',
      tz: 'UTC'
    }
  }
};

server.stdin.write(JSON.stringify(request) + '\n');

server.stdout.on('data', (data) => {
  console.log('Response:', data.toString());
});

Run: node test.mjs

🚧 Known Limitations

1. No Sync: Events are stored locally only. No Google Calendar / Outlook sync.
2. No Notifications: Server doesn't send reminders or alerts.
3. Recurrence Complexity: Only supports simple rules (no "2nd Tuesday of month").
4. Performance: Recurrence expansion is brute-force iteration (acceptable for <1000 instances).
5. No Conflict Detection: Doesn't prevent overlapping events.

🔮 Future Extensions

• Calendar Sync: Integrate with Google Calendar API, Microsoft Graph
• Notifications: Email/SMS reminders via Twilio, SendGrid
• Search: Full-text search on event titles/notes
• Attachments: Store files/links with events
• Attendees: Multi-user support with invitations
• Conflict Detection: Warn about overlapping events
• Advanced Recurrence: RRULE support (RFC 5545)

📚 Design Decisions

Why Luxon over Moment/Date-fns?

• Immutable: Safer API, no accidental mutations
• IANA Timezone Support: Built-in, no extra plugins
• Modern: Active development, ESM-first

Why SQLite over JSON Files?

• ACID Guarantees: Atomic writes, no corruption
• Indexes: Fast lookups on start_utc, idempotency_key
• Constraints: Unique keys enforced at DB level
• Scalability: Handles thousands of events efficiently

Why Virtual Instances for Recurrence?

• Storage Efficiency: One row instead of hundreds
• Flexibility: Change recurrence rule retroactively
• Cancellations: Track exceptions cleanly

📄 License

ISC

---

Built with ❤️ for the MCP ecosystem