Google Calendar MCP Server

A Model Context Protocol (MCP) server that provides Google Calendar integration for AI assistants like Claude.

Features

• Multi-Account Support: Connect multiple Google accounts (e.g., work, personal) and query them simultaneously
• Multi-Calendar Support: List events from multiple calendars in a single request
• Cross-Account Conflicts: Detect overlapping events across any combination of calendars
• Event Management: Create, update, delete, and search calendar events
• Recurring Events: Advanced modification capabilities for recurring events
• Free/Busy Queries: Check availability across calendars
• Smart Scheduling: Natural language understanding for dates and times
• Intelligent Import: Add calendar events from images, PDFs, or web links

Quick Start

Don't want to set up a Google Cloud project? Cocal is a hosted option that works in Claude on desktop and mobile.

Prerequisites

1. A Google Cloud project with the Calendar API enabled
2. OAuth 2.0 credentials (Desktop app type)

Google Cloud Setup

1. Go to the Google Cloud Console
2. Create a new project or select an existing one.
3. Enable the Google Calendar API for your project. Ensure that the right project is selected from the top bar before enabling the API.
4. Create OAuth 2.0 credentials:

• Go to Credentials
• Click "Create Credentials" > "OAuth client ID"
• Choose "User data" for the type of data that the app will be accessing
• Add your app name and contact information
• Add the following scopes (optional):
• https://www.googleapis.com/auth/calendar.events and https://www.googleapis.com/auth/calendar
• Select "Desktop app" as the application type (Important!)
• Save the auth key, you'll need to add its path to the JSON in the next step
• Add your email address as a test user under the Audience screen
• Note: it might take a few minutes for the test user to be added. The OAuth consent will not allow you to proceed until the test user has propagated.
• Note about test mode: While an app is in test mode the auth tokens will expire after 1 week and need to be refreshed (see Re-authentication section below).

Installation

Option 1: Use with npx (Recommended)

Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      "args": ["@cocal/google-calendar-mcp"],
      "env": {
        "GOOGLE_OAUTH_CREDENTIALS": "/path/to/your/gcp-oauth.keys.json"
      }
    }
  }
}

⚠️ Important Note for npx Users: When using npx, you must specify the credentials file path using the GOOGLE_OAUTH_CREDENTIALS environment variable.

Option 2: Local Installation

git clone https://github.com/nspady/google-calendar-mcp.git
cd google-calendar-mcp
npm install
npm run build

Then add to Claude Desktop config using the local path or by specifying the path with the GOOGLE_OAUTH_CREDENTIALS environment variable.

Option 3: Docker Installation

git clone https://github.com/nspady/google-calendar-mcp.git
cd google-calendar-mcp
cp /path/to/your/gcp-oauth.keys.json .
docker compose up

See the Docker deployment guide for detailed configuration options including HTTP transport mode.

First Run

1. Start Claude Desktop
2. Ask Claude to authenticate with the Google Calendar MCP server (e.g., "Authenticate with Google Calendar"). This step is required before using any calendar tool — without it, requests will fail with a -32600 error.
3. Complete the OAuth flow in your browser
4. You're ready to use calendar features!

Using Claude Code? The same steps apply — just ask Claude to authenticate with the Google Calendar MCP server from your CLI session before using any calendar tool.

Re-authentication

If you're in test mode (default), tokens expire after 7 days. If you are using a client like Claude Desktop it should open up a browser window to automatically re-auth. However, if you see authentication errors you can also resolve by following these steps:

For npx users:

export GOOGLE_OAUTH_CREDENTIALS="/path/to/your/gcp-oauth.keys.json"
npx @cocal/google-calendar-mcp auth

For local installation:

npm run auth

To avoid weekly re-authentication, publish your app to production mode (without verification):

1. Go to Google Cloud Console → "APIs & Services" → "OAuth consent screen"
2. Click "PUBLISH APP" and confirm
3. Your tokens will no longer expire after 7 days but Google will show a warning about the app being unverified.

See Authentication Guide for details.

Service Account Authentication (optional)

A service account carries its own long-lived key, so there is no browser consent step and no refresh token to expire. This is the alternative to publishing your OAuth app when the weekly re-authentication above is impractical — headless servers, containers, CI, or an app you would rather leave in Testing status.

Which calendars this works for

Sharing is what grants access — the service account is a separate identity and sees nothing by default. Domain-wide delegation is not required for the personal-calendar case; it is only needed if you want the service account to act as a user.

Limitations

• Attendees cannot be invited. The API rejects this with *"Service accounts cannot

invite attendees without Domain-Wide Delegation of Authority"*. Everything else — creating, updating, deleting, searching, free/busy — works normally.

• calendarId must be explicit. primary refers to the service account's own,

empty calendar; pass the calendar's address (e.g. you@gmail.com) instead.

• list-calendars returns nothing. A calendar shared with a service account does not

appear in its calendarList unless explicitly added. Address calendars by id.

Setup

1. Create a service account and a JSON key in your Google Cloud project:

   gcloud iam service-accounts create calendar-mcp --project=YOUR_PROJECT
   gcloud iam service-accounts keys create service-account.json \
     --iam-account=calendar-mcp@YOUR_PROJECT.iam.gserviceaccount.com

1. In Google Calendar, open Settings → your calendar → Share with specific people,

add the service account's e-mail and grant "Make changes to events".

1. Point the server at the key:

   {
     "mcpServers": {
       "google-calendar": {
         "command": "npx",
         "args": ["@cocal/google-calendar-mcp"],
         "env": {
           "GOOGLE_SERVICE_ACCOUNT_KEY": "/path/to/service-account.json"
         }
       }
     }
   }

The key is detected by its contents ("type": "service_account"), not by a mode flag, so switching an existing install over is a one-file change. Three things are consulted, and the first one that yields an answer wins:

1. GOOGLE_SERVICE_ACCOUNT_KEY — an explicit demand for service account mode. If

that file is missing, unreadable, or not a service account key, the server fails to start and says so, rather than falling back to OAuth and leaving you to guess why.