Google Calendar MCP Server

A Model Context Protocol (MCP) server that connects Claude Desktop to Google Calendar — letting Claude read, create, update, and delete events directly from conversation.

Demo

Ask Claude things like:

"What's on my calendar this week?"
"Schedule a meeting with John tomorrow at 2pm"
"Find a free hour on Friday afternoon"
"Move my 3pm call to 4pm"

Tools

Tool	Description
`list_events`	List upcoming events for the next N days
`search_events`	Search events by keyword
`create_event`	Create a new event with title, time, location, attendees
`update_event`	Edit an existing event
`delete_event`	Delete an event by ID
`find_free_time`	Find open time slots on a given day (8am–6pm)

Tech Stack

TypeScript + Node.js
MCP SDK (@modelcontextprotocol/sdk) — Anthropic's standard for AI tool integration
Google Calendar API v3 via googleapis
OAuth 2.0 — desktop app flow with local callback server

Setup

1. Google Cloud Console

Create a project at console.cloud.google.com
Enable the Google Calendar API
Create OAuth credentials → Desktop app → download credentials.json
Add your email as a test user under OAuth consent screen → Audience

2. Install & Authenticate

git clone https://github.com/coldinnn/google-calendar-mcp
cd google-calendar-mcp
npm install
cp /path/to/downloaded/credentials.json .
npm run setup   # opens browser for OAuth — saves token.json

3. Connect to Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Restart Claude Desktop — the calendar tools will appear automatically.

Project Structure

src/
  auth.ts      # OAuth2 client — loads credentials, refreshes tokens
  setup.ts     # One-time setup: generates auth URL, catches callback, saves token
  server.ts    # MCP server — defines all 6 tools

How It Works

setup.ts starts a local HTTP server on port 3000, generates an OAuth URL, and waits for Google to redirect back with an authorization code. It exchanges the code for access + refresh tokens and saves them to token.json.

server.ts uses McpServer + StdioServerTransport from the MCP SDK. Claude Desktop launches it as a subprocess and communicates over stdin/stdout. Each tool call hits the Google Calendar API and returns formatted text back to Claude.

Token refresh is handled automatically on every request — no manual re-auth needed.

License

MIT