# mcp-google-calendar

A minimal MCP server for Google Calendar using OAuth 2.0 and the Google
Calendar API.

## Tools

- `connect_calendar()` and `calendar_health()`
- `list_calendars()`
- `list_events(...)` and `get_event(...)`
- `create_event(...)`, with recurrence, attendees, and optional Google Meet
- `update_event(...)` and `delete_event(...)`
- `list_calendar_acl(...)` and `share_calendar(...)`
- `watch_calendar_events(...)`
- `list_event_changes(...)`

`create_event`, `update_event`, `delete_event`, `share_calendar`, and
`watch_calendar_events` have external side effects. MCP clients should request
explicit confirmation before calling them.

## Setup

1. Enable the Google Calendar API in Google Cloud Console.
2. Create an OAuth client with application type **Desktop app**.
3. Download the OAuth file as `credentials.json` into this directory.
4. Install dependencies and start the server:

```bash
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
python server.py
```

Authorization is a two-step tool call, so it works the same whether this server
runs on your laptop or on a machine with no browser at all:

1. Call `google_auth_start`. It returns an authorization URL.
2. Approve access in a browser — any browser, on any device.
3. Call `google_auth_complete` with the URL you land on.

On a desktop, steps 2 and 3 usually happen by themselves: the browser is opened
for you and the redirect is caught on `http://localhost:8765` (set
`GOOGLE_OAUTH_PORT` to change it).

On a headless server, or when you approve on a phone, that redirect cannot be
reached and the browser shows a connection error. That is expected — the
authorization code is in the address bar. Copy the whole URL
(`http://localhost:8765/?code=...`) and pass it to `google_auth_complete`, which
also accepts the bare `code` value.

Both `credentials.json` and `token.json` are ignored by Git.

Optional `.env` configuration:

```env
GOOGLE_CREDENTIALS=credentials.json
GOOGLE_TOKEN=token.json
GOOGLE_CALENDAR_TIMEZONE=Asia/Jakarta
```

## MCP Client

```json
{
  "mcpServers": {
    "google-calendar": {
      "command": "python",
      "args": [
        "C:/Users/your-user/Documents/GitHub/mcp-google-calendar/server.py"
      ]
    }
  }
}
```