Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@calendar-mcp what events do I have this week?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that exposes read-only
calendar data from iCal (.ics) feed URLs to an MCP-compatible agent.
You point it at one or more iCal URLs. It fetches them on a regular interval, expands recurring events, caches everything in memory, and offers tools an agent can call to answer questions like "what's on my calendar this week?", "am I free Thursday afternoon?", or "find events mentioning 'dentist'".
It never writes to any calendar — iCal feeds are pull-only sources.
Requires Python ≥ 3.11 and uv.
uv syncRelated MCP server: iCloud Calendar MCP
Copy the example config and edit it:
cp calendars.example.toml calendars.tomlrefresh_interval_minutes = 15 # how often to re-fetch (min 5)
default_timezone = "America/New_York" # applied to floating times & agenda math
max_results = 200 # cap on events returned per tool call
[[calendars]]
name = "Work"
url = "https://example.com/work.ics"
[[calendars]]
name = "Family"
url = "https://calendar.google.com/.../basic.ics"Feed URLs are secrets. Google/Apple/Outlook "private address" URLs embed an access token. The server never logs or exposes the URL — only the friendly
nameappears in output.calendars.tomlis git-ignored; keep it private.
uv run calendar-mcp calendars.tomlThe server speaks the MCP stdio protocol, so it's normally launched by your MCP client rather than by hand. Register it like this:
{
"mcpServers": {
"calendar": {
"command": "uv",
"args": ["run", "calendar-mcp", "/absolute/path/to/calendars.toml"]
}
}
}Tool | What it does |
| Each feed's refresh state, event count, last success (no URLs). |
| Events in a window (recurrences expanded), sorted by start. |
| Full detail (description, attendees) for one event UID. |
| Case-insensitive match on summary/description/location. |
| Merged busy intervals and the free gaps between them. |
| Convenience: |
| Force an immediate re-fetch of all feeds. |
Times are ISO-8601. If you omit a window, a sensible default is used. Results are
capped at max_results and flagged truncated when trimmed, so large calendars
don't overrun the agent's context.
Recurrence (RRULE/EXDATE/RECURRENCE-ID overrides) is expanded by
recurring-ical-events.
Timezones: UTC, TZID, and floating times are all normalized to
timezone-aware ISO-8601; floating times get default_timezone.
Resilience: a feed that fails to fetch or parse keeps its last-known-good data and records the error in its status — it never wipes the cache or crashes the refresh loop.
HTTP efficiency: ETag/Last-Modified are stored and sent as conditional
requests, so an unchanged feed returns 304 and skips re-parsing.
uv run pytest # unit tests + fixturesWriting/creating events, tasks (VTODO) and reminders (VALARM), an HTTP/daemon
transport, and on-disk cache persistence across restarts.
Copyright (C) 2026 Jeremy Beker.
This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
It is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
This server cannot be deployed
Calendar API for AI agents: events, availability, Google/Microsoft setup, scheduling, and iCal.
GDPR-compliant calendar access for AI assistants: read, create, edit, RSVP. Google, MS 365, Apple.
Agent-Native Google Calendar - manage events, sync, and public booking
Manage Google, Outlook & Apple calendars and create private sync rules from chat.
