Calendar MCP

1# Calendar MCP
2 
3A Deno monorepo containing packages for macOS Calendar access:
4 
5- **[@wyattjoh/calendar](packages/calendar)** - Core library for read-only macOS Calendar database access
6- **[@wyattjoh/calendar-mcp](packages/calendar-mcp)** - Model Context Protocol (MCP) server for LLM integration
7 
8## Features
9 
10- Search calendar events by title/summary
11- Get recent past events
12- Get upcoming events
13- Retrieve events within date ranges
14- Get today's events with conflict detection
15- Get detailed event information including location, URL, and recurrence
16- Filter rescheduled events
17 
18## Requirements
19 
20- macOS (Calendar is only available on macOS)
21- Deno 2.x or later
22- Read access to `~/Library/Calendars/Calendar.sqlitedb`
23 
24## Packages
25 
26### @wyattjoh/calendar
27 
28Core library for accessing Calendar data:
29 
30```bash
31deno add @wyattjoh/calendar
32```
33 
34```typescript
35import { openDatabase, searchEvents } from "@wyattjoh/calendar";
36 
37const db = openDatabase();
38try {
39  const events = searchEvents(db, { query: "meeting", limit: 10 });
40  console.log(events);
41} finally {
42  db.close();
43}
44```
45 
46[See full documentation](packages/calendar/README.md)
47 
48### @wyattjoh/calendar-mcp
49 
50MCP server for LLM integration:
51 
52```bash
53# Run directly from JSR
54deno run --allow-read --allow-env --allow-ffi --allow-sys jsr:@wyattjoh/calendar-mcp
55 
56# Or install globally
57deno install --global --allow-read --allow-env --allow-ffi --allow-sys -n calendar-mcp jsr:@wyattjoh/calendar-mcp
58```
59 
60For Claude Desktop app integration, add this to your `claude_desktop_config.json`:
61 
62```json
63{
64  "mcpServers": {
65    "calendar": {
66      "command": "deno",
67      "args": [
68        "run",
69        "--allow-read",
70        "--allow-env",
71        "--allow-ffi",
72        "--allow-sys",
73        "jsr:@wyattjoh/calendar-mcp"
74      ]
75    }
76  }
77}
78```
79 
80### Option 2: From Source
81 
821. Clone this repository
832. Run the server:
84   ```bash
85   cd packages/calendar-mcp
86   deno run --allow-read --allow-env --allow-ffi --allow-sys mod.ts
87   # Or use the task:
88   deno task dev
89   ```
90 
91### Available Tools
92 
931. **get-recent-events** - Get recent past calendar events
94   - `limit` (optional): Number of events (1-100, default: 10)
95   - `includeRescheduled` (optional): Include original rescheduled events (default: false)
96 
972. **get-upcoming-events** - Get upcoming calendar events
98   - `limit` (optional): Number of events (1-100, default: 10)
99   - `includeRescheduled` (optional): Include original rescheduled events (default: false)
100 
1013. **get-events-by-date-range** - Get events within a date range
102   - `startDate` (required): Start date in ISO format (e.g., "2024-01-01")
103   - `endDate` (required): End date in ISO format (e.g., "2024-01-31")
104   - `includeRescheduled` (optional): Include original rescheduled events (default: false)
105 
1064. **search-events** - Search for events by title/summary
107   - `query` (required): Search query for event titles
108   - `limit` (optional): Maximum results (1-100, default: 20)
109   - `timeRange` (optional): "all", "past", or "future" (default: "all")
110   - `includeRescheduled` (optional): Include original rescheduled events (default: false)
111 
1125. **get-todays-events** - Get all events scheduled for today
113   - `includeRescheduled` (optional): Include original rescheduled events (default: false)
114 
1156. **get-event-details** - Get detailed information about a specific event
116   - `eventId` (required): The ROWID of the event
117 
118### Response Format
119 
120All tools return calendar events in this format:
121 
122```json
123{
124  "id": 12345,
125  "title": "Team Meeting",
126  "startTime": "2024-01-15T10:00:00.000Z",
127  "endTime": "2024-01-15T11:00:00.000Z",
128  "allDay": false,
129  "status": "confirmed",
130  "isRescheduled": false
131}
132```
133 
134Detailed events (from get-event-details) include additional fields:
135 
136```json
137{
138  "id": 12345,
139  "title": "Team Meeting",
140  "startTime": "2024-01-15T10:00:00.000Z",
141  "endTime": "2024-01-15T11:00:00.000Z",
142  "allDay": false,
143  "status": "confirmed",
144  "isRescheduled": false,
145  "description": "Weekly sync with the team",
146  "location": "Conference Room A",
147  "url": "https://meet.example.com/team",
148  "recurrenceRule": "FREQ=WEEKLY;INTERVAL=1",
149  "calendar": "Work"
150}
151```
152 
153## Security Notes
154 
155- This server runs with read-only access to the Calendar database
156- No events can be created, modified, or deleted
157- The server only accesses local data
158 
159## Development
160 
161This is a Deno workspace monorepo. All commands run from the root affect all packages.
162 
163```bash
164# Clone the repository
165git clone https://github.com/wyattjoh/calendar-mcp.git
166cd calendar-mcp
167 
168# Format all code
169deno task fmt
170 
171# Lint all packages
172deno task lint
173 
174# Type check all packages
175deno task check
176 
177# Run MCP server locally
178cd packages/calendar-mcp
179deno task dev
180 
181# Publish packages (CI/CD)
182deno publish
183```
184 
185### Working on Individual Packages
186 
187```bash
188# Work on @wyattjoh/calendar
189cd packages/calendar
190deno fmt
191deno lint
192deno check mod.ts
193 
194# Work on @wyattjoh/calendar-mcp
195cd packages/calendar-mcp
196deno run --allow-read --allow-env --allow-ffi --allow-sys mod.ts
197```
198 
199## License
200 
201MIT
202