Calendar MCP server

calendar-mcp

An MCP server that gives an LLM client read and write access to your Google Calendar. It runs as a single process — stdio by default, streamable HTTP optionally — and exposes 23 tools with structured output: listing and searching calendars and events, creating, updating, moving, RSVPing to and deleting events, free/busy queries, busyness analysis, recurring-event projection, and finding a mutual slot and booking it. On top of that it has a scheduling brain that knows your working hours: finding and booking focus time, detecting double-bookings across several accounts at once, proposing better times for a meeting, and auditing where your week actually went. Authentication is Google OAuth 2.0 (Desktop app flow); tokens are cached locally, per account, and refreshed automatically.

Quick start

1. Create Google OAuth credentials. In the Google Cloud console, enable the Google Calendar API, then create an OAuth client ID of type Desktop app. Copy the client ID and secret. (Details in Google Cloud setup.)

2. Set them in your environment, or in a .env file in the directory you run from (see example.env):

GOOGLE_CLIENT_ID='...'
GOOGLE_CLIENT_SECRET='...'

3. Sign in once, then add the server to your client:

uvx calendar-mcp-server auth

This opens a browser and saves a token in the config directory (see Accounts); if you already have a .gcp-saved-tokens.json or set TOKENFILEPATH, that file is used instead. Verify it with calendar-mcp check. Add more Google accounts with calendar-mcp auth --account work. After that the server runs non-interactively — it never opens a browser on its own unless you set CALENDARMCPALLOWBROWSERAUTH=1.

The PyPI distribution is calendar-mcp-server. It installs two identical console scripts, calendar-mcp and calendar-mcp-server, so uvx calendar-mcp-server and a local calendar-mcp are the same command.

Client configuration

Claude Code

claude mcp add calendar \
  --env GOOGLE_CLIENT_ID=... \
  --env GOOGLE_CLIENT_SECRET=... \
  -- uvx calendar-mcp-server

Claude Desktop — claudedesktopconfig.json:

{
  "mcpServers": {
    "calendar": {
      "command": "uvx",
      "args": ["calendar-mcp-server"],
      "env": {
        "GOOGLE_CLIENT_ID": "...",
        "GOOGLE_CLIENT_SECRET": "...",
        "TOKEN_FILE_PATH": "/absolute/path/to/.gcp-saved-tokens.json"
      }
    }
  }
}

Cursor — .cursor/mcp.json (project) or ~/.cursor/mcp.json (global): same mcpServers block as above.

Any other client that speaks the standard mcpServers JSON takes the same entry. TOKENFILEPATH is optional now that tokens default to the OS config directory, which does not depend on the working directory the client picks — but if you do set it, make it an absolute path.

Remote / HTTP mode

calendar-mcp --transport http --host 127.0.0.1 --port 8000

The MCP endpoint is then http://127.0.0.1:8000/mcp (change the path with --path).

There is no authentication layer on the HTTP transport yet. Anyone who can reach the endpoint gets full access to the calendar the saved token belongs to. Bind it to loopback, or expose it only behind a trusted reverse proxy that authenticates, or on a private network such as a tailnet. Do not put it on a public interface.

Tools

Read-only tools never change anything. "Writes" tools create or modify events; delete_event is the only one that destroys data.

Calendars and events

Shortened. The full README is on GitHub.