mcp-server-google-calendar

A minimal Model Context Protocol server for Google Calendar. Purpose-built for use with AI assistants (OpenClaw, Claude Desktop, etc.).

Uses StreamableHTTPServerTransport — stateless, one transport per request. No supergateway, no SSE stream management.

Tools

Tool	Description
list_calendars	List all calendars on the authenticated account
list_events	List events in a time range (supports recurring event expansion)
search_events	Full-text search across summary, description, location, and attendees
get_event	Fetch full details of a single event by ID
get_freebusy	Query free/busy blocks for one or more calendars

Requirements

• A Google Cloud project with the Calendar API enabled
• OAuth 2.0 credentials (credentials.json / gcp-oauth.keys.json)
• A valid tokens.json obtained via the OAuth flow

The server reads credentials and tokens from disk at startup and writes refreshed tokens back automatically.

Token formats

Both flat tokens and the nested format used by @cocal/google-calendar-mcp are supported:

// flat
{ "access_token": "...", "refresh_token": "...", "expiry_date": 1234567890 }

// nested
{ "normal": { "access_token": "...", "refresh_token": "...", "expiry_date": 1234567890 } }

Running with Docker

docker run -p 3000:3000 \
  -e GOOGLE_OAUTH_CREDENTIALS=/config/gcp-oauth.keys.json \
  -e GOOGLE_TOKENS_PATH=/config/tokens.json \
  -v /path/to/your/config:/config \
  mcp-server-google-calendar

docker-compose

google-calendar-mcp:
  build:
    context: ./google-calendar-mcp
  environment:
    GOOGLE_OAUTH_CREDENTIALS: /config/gcp-oauth.keys.json
    GOOGLE_TOKENS_PATH: /config/tokens.json
    HTTP_PORT: "3000"
  volumes:
    - /path/to/config:/config
  restart: unless-stopped

Environment variables

Variable	Default	Description
GOOGLE_OAUTH_CREDENTIALS	/config/gcp-oauth.keys.json	Path to the OAuth client credentials file
GOOGLE_TOKENS_PATH	/config/tokens.json	Path to the stored OAuth tokens file
HTTP_PORT	3000	Port the HTTP server listens on

Endpoints

Endpoint	Description
GET /healthz	Returns ok with HTTP 200 — suitable for Docker healthchecks
POST /mcp	MCP protocol endpoint (StreamableHTTP)

Connecting to an MCP client

In your MCP client config, point to /mcp:

{
  "mcp": {
    "servers": {
      "google-calendar": {
        "url": "http://localhost:3000/mcp"
      }
    }
  }
}

Getting credentials

1. Go to the Google Cloud Console
2. Create a project and enable the Google Calendar API
3. Create OAuth 2.0 credentials (Desktop app type)
4. Download the credentials as gcp-oauth.keys.json
5. Run the OAuth flow once to obtain tokens.json — for example using @cocal/google-calendar-mcp's auth command, or any standard OAuth2 PKCE flow

License

MIT