# Google Calendar MCP Server

An MCP server that exposes your Google Calendar as tools Claude can call: `list_events`, `create_event`, `update_event`, `delete_event`, `find_free_busy`.

## 1. Google Cloud setup (one-time)

1. Go to the [Google Cloud Console](https://console.cloud.google.com/), create (or pick) a project.
2. **APIs & Services → Library** → enable **Google Calendar API**.
3. **APIs & Services → OAuth consent screen** → set it up (External is fine, you can leave it in "Testing" and add your own Google account as a test user — no Google review needed for personal use).
4. **APIs & Services → Credentials → Create Credentials → OAuth client ID** → Application type: **Desktop app**.
5. Under that client, add an **Authorized redirect URI**: `http://localhost:3000/oauth2callback`
6. Copy the generated Client ID and Client Secret.

## 2. Project setup

```bash
npm install
cp .env.example .env
# paste your Client ID / Client Secret into .env
```

## 3. Authorize (one-time)

```bash
npm run authorize
```

This opens a Google consent URL in your terminal — open it in a browser, sign in, grant access. It saves the resulting tokens to `token.json` (already git-ignored — never commit this file, it's equivalent to a password).

## 4. Build and run

```bash
npm run build
npm start
```

You should see `Google Calendar MCP server running on stdio` on stderr. Stop it with Ctrl+C — Claude Desktop will launch it itself in normal use.

## 5. Connect it to Claude Desktop

Add this to your Claude Desktop config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "google-calendar": {
      "command": "node",
      "args": ["/absolute/path/to/calendar-mcp-server/build/src/index.js"]
    }
  }
}
```

Restart Claude Desktop. You should see the calendar tools available (the hammer/tools icon).

## Notes

- Scope used is `https://www.googleapis.com/auth/calendar` (full read/write on your calendars). Narrow this in `src/auth.ts` if you want read-only or events-only access.
- `calendarId` defaults to `"primary"` on every tool — pass a specific calendar's ID (visible in Google Calendar → Settings) to target another calendar.
- If you ever revoke access or the refresh token stops working, delete `token.json` and re-run `npm run authorize`.