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

1. Create a project at console.cloud.google.com
2. Enable the Google Calendar API
3. Create OAuth credentials → Desktop app → download credentials.json
4. 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