# cal-mcp

A read-only MCP server that reads the local Apple Calendar on this Mac. It uses
the streamable HTTP transport.

Written for the mcp Python SDK version 2.x. In that version the class `FastMCP`
is named `MCPServer`, and it lives in `mcp.server.mcpserver`.

## Install

```bash
git clone https://github.com/burghr/cal-mcp.git
cd cal-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

## Grant calendar access

macOS grants calendar access to the program that starts the server, not to the
server itself. The first start opens a prompt. Approve it.

To change the grant later, open System Settings, then Privacy & Security, then
Calendars.

## Start the server

```bash
python server.py
```

The endpoint is `http://127.0.0.1:8001/mcp`.

Set `MCP_HOST`, `MCP_PORT`, or `CAL_NOTES_LIMIT` to change the defaults. Port
8001 keeps this server clear of `snow-mcp`, which uses port 8000.

## Connect Claude Code

```bash
claude mcp add --transport http cal-mcp http://127.0.0.1:8001/mcp
```

## Tools

- `ping` tests the connection.
- `list_calendars` lists the calendar titles on this Mac.
- `get_today_events` returns the events of today.
- `get_events_for_date` returns the events of one day.
- `get_events_in_range` returns the events between two days.

Every tool except `ping` accepts an optional `calendars` list of titles. Omit
the list to read every calendar.

## Read-only

The server calls EventKit to read events. It never saves, changes, or deletes
an event.

## Start it at login

`com.burghr.cal-mcp.plist` is a launchd agent that starts the server at login
and restarts it if it stops. Replace `YOUR-USERNAME` in the file with your own
short user name, copy it to `~/Library/LaunchAgents/`, then run:

```bash
launchctl load ~/Library/LaunchAgents/com.burghr.cal-mcp.plist
```

## Your data stays here

The server binds to `127.0.0.1`, so nothing outside this Mac can reach it, and
it sends your events nowhere. The only thing that reads them is whatever MCP
client you point at the local endpoint.

## License

MIT. See `LICENSE`.