honest-calendar-mcp

Local Google Calendar MCP server. Your calendar data never leaves your machine except to Google. No third party in the middle.

Companion project to honest-gmail-mcp.

Why

Most Calendar integrations for AI assistants route your event data through a hosted service that sees everything: meetings, attendees, locations, private descriptions. This one doesn't.

Data flow: You ↔ this server (on your machine) ↔ Google Calendar API. That's it.

You can read the entire server — one file, a few hundred lines of Python — and confirm exactly what it can and cannot do.

Features

Six tools exposed over MCP:

• list_calendars — all calendars available on this account
• list_events — events in a calendar within a time range, with optional free-text search
• get_event — full details of a single event
• create_event — new event (timed or all-day), with attendees, description, location, timezone, recurrence (RRULE), transparency (busy/free), and reminders
• update_event — partial patch of an existing event
• delete_event — delete an event

All tools that send invites accept a send_updates parameter (none by default — no email is sent unless you explicitly ask for it).

Requirements

• Python 3.10+
• A Google account you want to give it access to
• A one-time setup in Google Cloud Console (~10 min, can reuse the OAuth client from honest-gmail-mcp if you already set that up)

Setup

1. Clone + install

git clone https://github.com/bartosz-kuc/honest-calendar-mcp.git
cd honest-calendar-mcp
python3 -m venv venv
./venv/bin/pip install -r requirements.txt

On Windows, use python instead of python3, and venv\Scripts\pip / venv\Scripts\python (venv\Scripts\python.exe in client configs) wherever this README shows venv/bin/....

2. Get Google OAuth credentials

Same process as honest-gmail-mcp — a Desktop-app OAuth client from your own Google Cloud project. If you already have a project set up, just enable the Calendar API on it:

1. https://console.cloud.google.com/ (signed in with the account you want to authorize)
2. Select existing project (or create new one)
3. APIs & Services → Library → search Google Calendar API → Enable
4. Reuse existing OAuth consent screen / client, OR create new — Desktop app type
5. Save credentials.json in this repo's root directory

3. Authorize (one-time OAuth)

./venv/bin/python authorize.py

Browser opens → sign in → Allow. Token saved locally as token.json. (If no token exists, the server also starts this flow on the first tool call.)

4. Register with your MCP client

Claude Code:

claude mcp add calendar-personal /absolute/path/to/venv/bin/python /absolute/path/to/server.py

Claude Desktop: edit claude_desktop_config.json:

{
  "mcpServers": {
    "calendar-personal": {
      "command": "/absolute/path/to/venv/bin/python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

5. Multiple accounts (optional)

Run one server instance per Google account, each with its own token file — no code changes. Three env vars override the defaults:

Authorize a second account (writes a separate token; sign in as that account in the browser):

CALENDAR_TOKEN_PATH="$PWD/token.work.json" ./venv/bin/python authorize.py

(PowerShell: $env:CALENDAR_TOKEN_PATH = "$PWD\token.work.json", then venv\Scripts\python authorize.py.)

Then register a second instance pointing at that token, e.g. in claude_desktop_config.json:

{
  "mcpServers": {
    "calendar-personal": {
      "command": "/absolute/path/to/venv/bin/python",
      "args": ["/absolute/path/to/server.py"]
    },
    "calendar-work": {
      "command": "/absolute/path/to/venv/bin/python",
      "args": ["/absolute/path/to/server.py"],
      "env": {
        "CALENDAR_TOKEN_PATH": "/absolute/path/to/token.work.json",
        "CALENDAR_SERVER_NAME": "calendar-work"
      }
    }
  }
}

Alternative: install from PyPI (uvx)

The package is published on PyPI as honest-calendar-mcp. Installed as a package, the default credentials.json / token.json paths resolve next to the installed module (inside the environment's site-packages), so set absolute paths with the env vars from step 5. This needs version 0.2.0 or newer: 0.1.0 does not read these env vars and fails to start with mcp 2.x.

{
  "mcpServers": {
    "calendar-personal": {
      "command": "uvx",
      "args": ["honest-calendar-mcp"],
      "env": {
        "CALENDAR_CREDENTIALS_PATH": "/absolute/path/to/credentials.json",
        "CALENDAR_TOKEN_PATH": "/absolute/path/to/token.json"
      }
    }
  }
}

authorize.py is not part of the package. If the token file does not exist yet, the server opens the browser for OAuth on the first tool call and writes the token to CALENDAR_TOKEN_PATH.

Example usage

"What's on my calendar tomorrow?"

AI calls list_events with tomorrow's time range → gets back events with summary, start, end, attendees.

"Book a 1h call with alice@example.com next Thursday at 15:00."

AI calls create_event with summary, start, end, attendees, send_updates: "all" if you want Alice invited.

"Add my Tuesday 19:30 kettlebells class every week, mark me free, no reminders."

AI calls create_event with recurrence: ["RRULE:FREQ=WEEKLY"], transparency: "transparent", and reminders: {"useDefault": false}.

Data flow (detail)

Your AI client (Claude Code / Claude Desktop)
         ↕  MCP protocol over stdio (local process pipe)
This server (Python, on your machine)
         ↕  HTTPS to googleapis.com
Google Calendar API

No cloud middle. No telemetry. credentials.json and every token*.json stay on your disk and are .gitignored.

Security notes

• You own the OAuth client. Nobody else can revoke, rotate, or misuse it.
• Revoke anytime at https://myaccount.google.com/permissions.
• Scope requested: calendar (full read/write on all your calendars). Google does not offer read-only + write-only splits for the standard Calendar scope; the write-heavy nature of a calendar-editing tool needs full scope.
• No secrets in git. .gitignore blocks credentials.json, token.json, per-account token.*.json, and virtualenvs.
• send_updates defaults to "none" — the AI cannot accidentally spam attendees. You must explicitly ask for updates to be sent.

Author

Bartosz Kuć — Warsaw-based developer, JDG owner running skanfirmy.pl.

• Site: https://skanfirmy.pl

• GitHub: https://github.com/bartosz-kuc

• Email: firma@bartosza.pl

Consulting

Available for consulting on Polish tax and business integrations (KSeF, GUS/NFZ/GIOŚ APIs, mBank data), MCP server design, and AI-assisted tooling for JDGs and small teams. See skanfirmy.pl/uslugi for productized packages (audit 3k PLN, setup 8-15k PLN, retainer 2-4k PLN/mo), or reach out via email.

License

MIT — see LICENSE.