home / mcp / google calendar mcp server

Google Calendar MCP Server

Provides Google Calendar integration within MCP, enabling multi-account management, event operations, free/busy checks, and smart scheduling across calendars.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "nspady-google-calendar-mcp": {
      "command": "npx",
      "args": [
        "@cocal/google-calendar-mcp"
      ],
      "env": {
        "ENABLED_TOOLS": "list-events,get-current-time,create-event",
        "GOOGLE_OAUTH_CREDENTIALS": "/path/to/your/gcp-oauth.keys.json",
        "GOOGLE_CALENDAR_MCP_TOKEN_PATH": "/path/to/tokens"
      }
    }
  }
}

You can connect and manage multiple Google calendars from an MCP client, enabling you to query, create, update, and coordinate events across accounts and calendars with smart scheduling and image-based event import. This MCP server brings Google Calendar capabilities directly into your AI workflows, simplifying how you plan meetings, check availability, and handle recurring events.

How to use

You will integrate the Google Calendar MCP server with your MCP client or Claude Desktop by configuring an MCP server entry. The server supports multiple accounts and calendars, lets you create and modify events, checks free/busy availability across calendars, and handles recurring events with advanced modification options. Use it to ask for cross-calendar availability, import events from images, and manage invitations.

How to install

Prerequisites you need before installation: a Google Cloud project with the Calendar API enabled and OAuth 2.0 credentials for a Desktop app.

Install options you can choose from:

Option 1: Use with npx (Recommended) You will add the MCP server to your Claude Desktop configuration and run it via npx. Ensure you provide the credentials path through an environment variable.

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

Option 2: Local Installation You can clone the project, install dependencies, and build locally. Then configure Claude Desktop to point to the local runtime or to the credentials file.

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

If you prefer containerized deployment, you can run via Docker Compose with your credentials file in the container workspace.

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

First Run

To start using the calendar features, launch Claude Desktop. On first use, the server will prompt you to authenticate. Complete the OAuth flow in your browser, and you are ready to interact with your calendars.

Re-authentication

If tokens expire or you encounter authentication errors, re-authenticate using the appropriate command for your setup. In most cases, Claude Desktop will open a browser window to re-authenticate automatically.

Managing Multiple Accounts

You can connect and manage multiple Google accounts. Use the chat interface to add, list, or remove accounts without using a terminal, or use the CLI for initial setup. In a browser, you can also manage accounts at the accounts management page.

Example Usage

You can perform complex, multi-calendar queries and actions, such as checking cross-calendar availability, creating events from natural language inputs, and handling invitations across calendars.

Available Tools and Capabilities

The MCP server exposes a range of calendar-related tools, including listing calendars, listing and querying events, creating, updating, and deleting events, responding to invitations, checking free/busy across calendars, and managing connected accounts.

Available tools

list-calendars

List all available calendars for your connected Google accounts.

list-events

List events with date filtering across one or more calendars.

get-event

Retrieve details for a specific event by its ID.

search-events

Search events by text query across calendars.

create-event

Create new calendar events with specified details.

update-event

Update existing events by ID with new details.

delete-event

Delete events by ID.

respond-to-event

Respond to event invitations (Accept, Decline, Maybe, No Response).

get-freebusy

Check availability across calendars, including external calendars.

get-current-time

Get the current date and time in the calendar's timezone.

list-colors

List available event colors.

manage-accounts

Add, list, or remove connected Google accounts.