MCP 服务器

Calendar MCP Server

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

README

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

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