cal-scheduler MCP server

<!-- mcp-name: io.github.limey/cal-scheduler-mcp -->

If you are an agent installing this MCP, read AGENTS.md first.

cal-scheduler

A thin, timezone-correct MCP server for scheduling against any CalDAV calendar. It gives an LLM agent a small, strict set of calendar tools and does the deterministic, fiddly parts of iCalendar correctly so the model doesn't have to.

It is not an NLP layer: the agent phrases the request, the server validates it, rejects bad input loudly, and persists clean zoned .ics.

Why it exists

Most calendar tooling an LLM reaches for gets three things subtly wrong. cal-scheduler fixes them by construction:

weekly 9am stays 9am across a daylight-saving boundary instead of drifting an hour. Storing bare UTC is the classic cause of that drift.

• Stores zoned, not bare UTC. Events are written with TZID/VTIMEZONE, so a

a series starting on the 30th but set to repeat on the 1st), and normalises UNTIL to UTC under a zoned DTSTART as RFC 5545 requires.

• Validates recurrence. It rejects an RRULE whose anchor contradicts it (e.g.

instance (RECURRENCE-ID) without disturbing the rest of the series — the operations naive wrappers tend to lack.

• Does real single-occurrence edits. Exclude one instance (EXDATE) or move one

How it works

A small uv Python package that composes mature libraries rather than implementing a calendar engine:

It runs as a stdio MCP server that an MCP host (Claude, an agent harness, etc.) spawns as a subprocess.

Install

Requires Python ≥ 3.11. The package is on PyPI as cal-scheduler-mcp:

uv tool install cal-scheduler-mcp

(or pip install cal-scheduler-mcp, uvx --from cal-scheduler-mcp cal-scheduler, etc.)

For editable dev work, install from a clone:

# run straight from the repo with uv (no global install)
uv run --directory /path/to/cal-scheduler-mcp cal-scheduler

# or install the console script into a tool environment
gh repo clone limey/cal-scheduler-mcp
uv tool install --editable /path/to/cal-scheduler-mcp
# or, with SSH GitHub access, in one step:
uv tool install git+ssh://git@github.com/limey/cal-scheduler-mcp

Don't uv add cal-scheduler-mcp for the MCP — uv add writes

into whatever project you're sitting in, not into the tool

environment. For an MCP server (spawned as a subprocess),

uv tool install is the right shape.

Configure

All configuration is via environment variables:

Many MCP hosts strip inherited environment from stdio servers, so set these in the host's per-server env block rather than relying on the ambient shell.

Example MCP host config

Shortened. The full README is on GitHub.