Google Calendar MCP Server

An MCP (Model Context Protocol) server that exposes Google Calendar as tools for AI assistants like Claude. It acts as a bridge, allowing LLMs to read, create, update, delete, and search calendar events on your Google Calendar via the standardized MCP protocol over stdio.

Features

List events — Fetch calendar events within a given time range
Create events — Add new events with optional Google Meet video conferencing
Update events — Modify existing events (partial updates)
Delete events — Remove events by ID
Get event — Retrieve full details of a single event
List calendars — List all calendars accessible to the user
Search events — Free-text search across event titles, descriptions, and attendees
Quick add — Create events using natural language (e.g., "Lunch with John at 1pm tomorrow")

Prerequisites

Node.js (v18 or later)
npm
A Google Cloud Project with the Google Calendar API enabled

Setup

1. Google Cloud Configuration

Go to the Google Cloud Console.
Create a new project or select an existing one.
Enable the Google Calendar API (APIs & Services > Library).
Create OAuth 2.0 credentials:
- Go to APIs & Services > Credentials.
- Click Create Credentials > OAuth client ID.
- Choose Desktop app as the application type.
- Add http://localhost:3000 as an Authorized redirect URI.
- Download the JSON file.
Save the downloaded file as credentials.json in the project root.

2. Install Dependencies

npm install

3. Authenticate

Run the server for the first time:

npm run dev

A URL will be printed to the console. Open it in your browser, log into your Google account, and authorize the application. The tokens will be saved to calendar-token.json for subsequent runs.

Usage

Running the server

npm run build   # Compile TypeScript to JavaScript
npm start       # Start the server

Or combine both steps:

npm run dev

The server listens on stdin/stdout using the MCP stdio transport.

Integrating with an MCP Host

Add the following to your MCP host configuration (e.g., claude_desktop_config.json):

{
  "mcpServers": {
    "google-calendar": {
      "command": "node",
      "args": ["/path/to/google-calendar-mcp-server/dist/index.js"]
    }
  }
}

Tools

| Tool | Description | |---|---| | list_events | Fetch events in a time range (default: next 24 hours) | | create_event | Create a new event (supports Google Meet links) | | update_event | Update an existing event's fields | | delete_event | Delete an event by ID | | get_event | Get full details of a single event | | list_calendars | List all accessible calendars | | search_events | Free-text search across events | | quick_add_event | Natural-language event creation |

Scripts

| Script | Description | |---|---| | npm run build | Compile TypeScript to JavaScript | | npm start | Run the compiled server | | npm run dev | Build and run in one step |

Project Structure

├── src/
│   ├── index.ts              # MCP server entry point
│   ├── auth.ts               # OAuth2 authentication flow
│   └── tools/
│       ├── index.ts           # Tool registry
│       ├── list-events.ts
│       ├── create-event.ts
│       ├── update-event.ts
│       ├── delete-event.ts
│       ├── get-event.ts
│       ├── list-calendars.ts
│       ├── search-events.ts
│       └── quick-add-event.ts
├── dist/                     # Compiled JavaScript output
├── credentials.json          # OAuth client credentials (not committed)
├── calendar-token.json       # OAuth tokens (auto-generated, not committed)
├── package.json
└── tsconfig.json

Security

credentials.json and calendar-token.json contain sensitive OAuth credentials and tokens. They are excluded from version control via .gitignore.
The OAuth scope used is https://www.googleapis.com/auth/calendar, granting full read/write access to your calendars.
Token refresh is handled automatically — refreshed tokens are saved to calendar-token.json.

MCP Servers