Google Calendar MCP Server

Name: Google Calendar MCP Server
Author: Nathan Spady

Read, create and manage Google Calendar events across one or more Google accounts

By Nathan Spady (individual) TypeScript Local · stdio Productivity

GitHub npm Website

76 popularity score ★ 1.2k ↓ 13k/wk

Connect your client

Local (npm)

Add in one click

Add to Cursor Add to VS Code Add to LM Studio Add to Goose

Opens the app, which asks before it adds the server. Then replace each <NAME> in its settings with your value.

Or add it by command or config

It needs GOOGLE_OAUTH_CREDENTIALS. Replace each <NAME> with your value.

Claude CodeTerminal

claude mcp add google-calendar -e GOOGLE_OAUTH_CREDENTIALS=<GOOGLE_OAUTH_CREDENTIALS> -- npx @cocal/google-calendar-mcp

Claude Desktopclaude_desktop_config.json

{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      "args": [
        "@cocal/google-calendar-mcp"
      ],
      "env": {
        "GOOGLE_OAUTH_CREDENTIALS": "<GOOGLE_OAUTH_CREDENTIALS>"
      }
    }
  }
}

Cursor~/.cursor/mcp.json

{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      "args": [
        "@cocal/google-calendar-mcp"
      ],
      "env": {
        "GOOGLE_OAUTH_CREDENTIALS": "<GOOGLE_OAUTH_CREDENTIALS>"
      }
    }
  }
}

VS Code.vscode/mcp.json

{
  "servers": {
    "google-calendar": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "@cocal/google-calendar-mcp"
      ],
      "env": {
        "GOOGLE_OAUTH_CREDENTIALS": "<GOOGLE_OAUTH_CREDENTIALS>"
      }
    }
  }
}

Codex~/.codex/config.toml

[mcp_servers.google-calendar]
command = "npx"
args = ["@cocal/google-calendar-mcp"]

[mcp_servers.google-calendar.env]
GOOGLE_OAUTH_CREDENTIALS = "<GOOGLE_OAUTH_CREDENTIALS>"

Gemini CLITerminal

gemini mcp add --scope user -e GOOGLE_OAUTH_CREDENTIALS=<GOOGLE_OAUTH_CREDENTIALS> google-calendar npx -- @cocal/google-calendar-mcp

Local (container)

Add in one click

Add to Cursor Add to VS Code Add to LM Studio Add to Goose

Opens the app, which asks before it adds the server. Then replace each <NAME> in its settings with your value.

Or add it by command or config

It needs GOOGLE_OAUTH_CREDENTIALS. Replace each <NAME> with your value.

FirstTerminal

git clone https://github.com/nspady/google-calendar-mcp.git
cd google-calendar-mcp
cp <PATH_TO_GCP_OAUTH_KEYS_JSON> ./gcp-oauth.keys.json
chmod 644 ./gcp-oauth.keys.json
docker compose up -d
docker compose exec calendar-mcp npm run auth

Claude CodeTerminal

claude mcp add google-calendar -e GOOGLE_OAUTH_CREDENTIALS=<GOOGLE_OAUTH_CREDENTIALS> -- docker run -e GOOGLE_OAUTH_CREDENTIALS --rm -i --mount 'type=bind,src=<PATH_TO_GCP_OAUTH_KEYS_JSON>,dst=/app/gcp-oauth.keys.json' --mount 'type=volume,src=google-calendar-mcp_calendar-tokens,dst=/home/nodejs/.config/google-calendar-mcp' calendar-mcp

Claude Desktopclaude_desktop_config.json

{
  "mcpServers": {
    "google-calendar": {
      "command": "docker",
      "args": [
        "run",
        "-e",
        "GOOGLE_OAUTH_CREDENTIALS",
        "--rm",
        "-i",
        "--mount",
        "type=bind,src=<PATH_TO_GCP_OAUTH_KEYS_JSON>,dst=/app/gcp-oauth.keys.json",
        "--mount",
        "type=volume,src=google-calendar-mcp_calendar-tokens,dst=/home/nodejs/.config/google-calendar-mcp",
        "calendar-mcp"
      ],
      "env": {
        "GOOGLE_OAUTH_CREDENTIALS": "<GOOGLE_OAUTH_CREDENTIALS>"
      }
    }
  }
}

Cursor~/.cursor/mcp.json

{
  "mcpServers": {
    "google-calendar": {
      "command": "docker",
      "args": [
        "run",
        "-e",
        "GOOGLE_OAUTH_CREDENTIALS",
        "--rm",
        "-i",
        "--mount",
        "type=bind,src=<PATH_TO_GCP_OAUTH_KEYS_JSON>,dst=/app/gcp-oauth.keys.json",
        "--mount",
        "type=volume,src=google-calendar-mcp_calendar-tokens,dst=/home/nodejs/.config/google-calendar-mcp",
        "calendar-mcp"
      ],
      "env": {
        "GOOGLE_OAUTH_CREDENTIALS": "<GOOGLE_OAUTH_CREDENTIALS>"
      }
    }
  }
}

VS Code.vscode/mcp.json

{
  "servers": {
    "google-calendar": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-e",
        "GOOGLE_OAUTH_CREDENTIALS",
        "--rm",
        "-i",
        "--mount",
        "type=bind,src=<PATH_TO_GCP_OAUTH_KEYS_JSON>,dst=/app/gcp-oauth.keys.json",
        "--mount",
        "type=volume,src=google-calendar-mcp_calendar-tokens,dst=/home/nodejs/.config/google-calendar-mcp",
        "calendar-mcp"
      ],
      "env": {
        "GOOGLE_OAUTH_CREDENTIALS": "<GOOGLE_OAUTH_CREDENTIALS>"
      }
    }
  }
}

Codex~/.codex/config.toml

[mcp_servers.google-calendar]
command = "docker"
args = ["run", "-e", "GOOGLE_OAUTH_CREDENTIALS", "--rm", "-i", "--mount", "type=bind,src=<PATH_TO_GCP_OAUTH_KEYS_JSON>,dst=/app/gcp-oauth.keys.json", "--mount", "type=volume,src=google-calendar-mcp_calendar-tokens,dst=/home/nodejs/.config/google-calendar-mcp", "calendar-mcp"]

[mcp_servers.google-calendar.env]
GOOGLE_OAUTH_CREDENTIALS = "<GOOGLE_OAUTH_CREDENTIALS>"

Gemini CLITerminal

gemini mcp add --scope user -e GOOGLE_OAUTH_CREDENTIALS=<GOOGLE_OAUTH_CREDENTIALS> google-calendar docker -- run -e GOOGLE_OAUTH_CREDENTIALS --rm -i --mount 'type=bind,src=<PATH_TO_GCP_OAUTH_KEYS_JSON>,dst=/app/gcp-oauth.keys.json' --mount 'type=volume,src=google-calendar-mcp_calendar-tokens,dst=/home/nodejs/.config/google-calendar-mcp' calendar-mcp

Settings 12

`GOOGLE_OAUTH_CREDENTIALS`	Required: Absolute path to your OAuth desktop-app credentials JSON; required with npx. A service account key can be given via GOOGLE_SERVICE_ACCOUNT_KEY instead.
`GOOGLE_SERVICE_ACCOUNT_KEY`	Optional: Path to a service account key; switches to service account mode and fails startup if unusable.
`GOOGLE_SERVICE_ACCOUNT_SUBJECT`	Optional: Workspace user to impersonate with domain-wide delegation.
`GOOGLE_APPLICATION_CREDENTIALS`	Optional: Shared Google credentials file, used only when no OAuth credentials file is found.
`GOOGLE_CALENDAR_MCP_TOKEN_PATH`	Optional: Where sign-in tokens are stored; defaults under the user config directory.
`GOOGLE_ACCOUNT_MODE`	Optional: Account nickname for single-account operations and the auth command.
`ENABLED_TOOLS`	Optional: Comma-separated list of tools to expose; manage-accounts is always on.
`TRANSPORT`	Optional: stdio (default) or http.
`PORT`	Optional: Port for the HTTP transport, default 3000.
`HOST`	Optional: Bind address for the HTTP transport, default 127.0.0.1.
`GOOGLE_OAUTH_REDIRECT_BASE`	Optional: Public base URL for the OAuth callback when signing in through a tunnel or proxy.
`GOOGLE_CALENDAR_API_BASE_URL`	Optional: Send Calendar API calls to a proxy you control instead of googleapis.com.

In a container, a setting goes in with -e NAME=value after docker run.

What it does

Google Calendar MCP Server is a community-built server that connects an assistant to the Google Calendar API using credentials you create in your own Google Cloud project. It can list calendars, list and search events, fetch a single event, check free/busy time, and create, update or delete events, including whole batches of events in one call and edits to recurring series. It can also accept, decline or tentatively answer invitations and apply calendar colour labels.

Several Google accounts can be connected at once, for example work and personal. Read tools merge results from every connected account unless one is named, and write tools pick an account that has the right permissions. Accounts are added or removed through the manage-accounts tool, the CLI, or a small web page when it runs over HTTP.

It runs locally over stdio by default, from npm with npx, from a cloned and built checkout, or in a Docker container built from the repository. An HTTP transport is also available for local testing. Sign-in is normally an OAuth desktop-app flow in the browser; a Google service account key can be used instead for headless machines. The ENABLED_TOOLS setting trims the exposed tools, for instance to read-only ones.

The author also sells a separate hosted product, Cocal, which the README promotes; this page covers only the open-source server.

What it needs

Runtime	Node.jsorDocker

Node.js (an LTS release) for the npx or source routes, or Docker for the container route. A Google Cloud project with the Google Calendar API enabled and an OAuth 2.0 client of the Desktop app type, saved as a JSON key file, with your address added as a test user; alternatively a service account key with the target calendars shared to it. A Google account with a calendar.

Limits

While the OAuth app stays in Google's test mode, tokens expire after 7 days and you must sign in again; publishing the app avoids this but Google then shows an unverified-app warning. In service account mode it cannot invite attendees (without domain-wide delegation), list-calendars returns nothing, and calendar IDs must be given explicitly. Calendars shared with you by others are not reachable by a service account. Calendar tools fail until you have authenticated once. The HTTP mode has no authentication of its own and is meant for localhost only. Browser sign-in may fail on some non-Chromium browsers.

Who it suits

Suits people who want an assistant to plan around and edit their own Google Calendar from a local machine, especially with more than one Google account, and who are willing to set up a Google Cloud project and OAuth client themselves. It is not published by Google. Those who do not want to create Cloud credentials or handle weekly re-sign-in in test mode may prefer a hosted option such as the author's Cocal, which the README names. For a read-only setup, restrict it with ENABLED_TOOLS.

Tools 13

list-calendars: Lists the calendars the connected accounts can see
list-events: Lists events in a date range from one or more calendars
get-event: Fetches the full details of one event by its ID
search-events: Finds events matching a text query
create-event: Adds a new event, optionally with a colour label
create-events: Adds several events at once with shared defaults, without conflict checks
update-event: Changes an existing event, including its colour label or recurring instances
delete-event: Removes an event
respond-to-event: Answers an invitation: accept, decline, maybe or no response
get-freebusy: Reports busy and free time across calendars, including external ones
get-current-time: Returns the current date and time in the calendar's time zone
list-colors: Lists the legacy event colours and a calendar's custom event labels
manage-accounts: Adds, lists or removes connected Google accounts

Popularity

76 popularity score, on our list (the bar is 36)

★ 1.2k ↓ 13k/wk

GitHub stars	1,212	37 points
Stars in 30 days	+14	5.9 points
npm downloads, last week	13,362	33 points

Measured 2026-11-07. How the score works.

Where it is published

Code	nspady/google-calendar-mcp ★ 1.2k
npm	@cocal/google-calendar-mcp 2.8.1, 2026-10-29

What it can reach

Runs	On your machine
Reaches	Your account at a service, The internet
Changes things	Yes: it can write, send, create or delete
Sign-in	OAuth sign-in
Licence	MIT (npm)
Last code change	2026-10-29

Runs on your machine and calls the Google Calendar API with your own Google Cloud OAuth client; the requested scopes are calendar and calendar.events, giving read and write access to every calendar each connected account can see. Tools can create, change and delete events and answer invitations on your behalf. Tokens are stored in a local file (by default under ~/.config/google-calendar-mcp). A service account key, if used, does not expire and should be kept private. The optional HTTP transport has no authentication and is meant only for localhost. ENABLED_TOOLS can limit it to read tools, though manage-accounts always stays available.

Over time

GitHub stars 1.2k +14 (+1 %)

1.2k1.2k

8 Oct 20267 Nov 2026

npm downloads a week 13k +10k (+363 %)

26k743

20 Oct 20257 Nov 2026

Before the site measured it, read from npm's daily download counts.

Popularity score 76 +5 (+6 %)

7866

8 Oct 20267 Nov 2026

What is rising across the directory

Sources

Page checked 2026-10-14.

Badge for your README

Shows this server's rank in its category, and stars for a server that runs on your machine. It updates every hour.

MarkdownREADME.md

[![Google Calendar MCP Server on EveryMCPServer](https://everymcpserver.com/badge/google-calendar-mcp-3.svg)](https://everymcpserver.com/servers/google-calendar-mcp-3)

Connect your client

Add in one click

Or add it by command or config

Add in one click

Or add it by command or config

Settings 12

What it does

What it needs

Limits

Who it suits

Tools 13

Similar servers

Google Workspace MCP Server

Google Workspace MCP Server

Google Drive MCP Server

Work IQ Calendar MCP Server

mcp-google-sheets

Microsoft 365 MCP Server