# gcal-mcp
MCP server for Google Calendar. Provides four tools: list calendars, list/search events, create events, and modify events.
## Prerequisites
- [uv](https://docs.astral.sh/uv/)
- A Google Cloud project with the Calendar API enabled
## Google Cloud Setup
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a project (or select an existing one)
3. Enable the **Google Calendar API**
4. Go to **APIs & Services > Credentials**
5. Create an **OAuth 2.0 Client ID** of type **Desktop App**
6. Download the credentials JSON and save it to `~/.config/gcal-mcp/credentials.json`
7. Go to **OAuth consent screen** and add your Google account as a test user
## Install & Authenticate
```bash
make install # install dependencies
make auth # opens browser for OAuth consent, prints calendars on success
```
## Register with Claude Code
```bash
make register # adds gcal-mcp as a user-scoped MCP server
make unregister # removes it
```
## Tools
| Tool | Description |
|------|-------------|
| `list_calendars` | List all accessible calendars |
| `list_events` | List or search events (supports time range, free-text query) |
| `create_event` | Create an event (supports attendees, location, description) |
| `modify_event` | Patch an existing event (only provided fields are updated) |
Date/time values accept `YYYY-MM-DD` for all-day events or ISO datetime (`YYYY-MM-DDTHH:MM`) for timed events.
## File Locations
- Credentials: `~/.config/gcal-mcp/credentials.json`
- OAuth token: `~/.config/gcal-mcp/token.json`
