# 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](https://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

```bash
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`:

```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