# gcal-mcp

A Google Calendar MCP server using OAuth2 bearer token auth via the Dedalus MCP framework.

## Tools

### Calendars
- `gcal_list_calendars` - List all calendars accessible by the user
- `gcal_get_calendar` - Get details of a specific calendar
- `gcal_create_calendar` - Create a secondary calendar
- `gcal_delete_calendar` - Delete a secondary calendar
- `gcal_clear_calendar` - Clear a calendar (deletes all events)
- `gcal_patch_calendar` - Patch calendar metadata
- `gcal_update_calendar` - Update calendar metadata (full replace)

### Calendar List
- `gcal_calendarlist_get` - Get a calendar list entry
- `gcal_calendarlist_insert` - Insert an existing calendar into the user's calendar list
- `gcal_calendarlist_delete` - Remove a calendar from the user's calendar list
- `gcal_calendarlist_patch` - Patch a calendar list entry
- `gcal_calendarlist_update` - Update a calendar list entry (full replace)

### Events
- `gcal_list_events` - List events from a calendar
- `gcal_get_event` - Get a specific event by ID
- `gcal_search_events` - Search for events by text query
- `gcal_get_event_instances` - Get instances of a recurring event
- `gcal_create_event` - Create an event
- `gcal_delete_event` - Delete an event
- `gcal_patch_event` - Patch an event (partial update)
- `gcal_update_event` - Update an event (full replace)
- `gcal_quick_add_event` - Quick add an event from a text string
- `gcal_move_event` - Move an event to another calendar
- `gcal_import_event` - Import an event (creates a private copy)

### Free/Busy
- `gcal_get_freebusy` - Query free/busy information for calendars

### Settings
- `gcal_get_settings` - Get user's calendar settings
- `gcal_get_setting` - Get a specific calendar setting

### Colors
- `gcal_get_colors` - Get available calendar and event colors

### Watch (Webhooks)
- `gcal_channels_stop` - Stop watching a channel
- `gcal_events_watch` - Watch for changes to Events resources
- `gcal_calendarlist_watch` - Watch for changes to CalendarList resources
- `gcal_settings_watch` - Watch for changes to Settings resources

---

## For MCP Users

Use this section if you want to **call** the gcal-mcp server from your own application via the Dedalus SDK.

### Prerequisites

1. A Dedalus API key (`dsk-live-*` or `dsk-test-*`)
2. The `dedalus-labs` Python SDK: `pip install dedalus-labs`

### Quick Start

See [`src/_client.py`](src/_client.py) for the complete working example.

### OAuth Flow

1. Your first request raises `AuthenticationError` with a `connect_url`
2. Open the URL in a browser to authorize Google Calendar access
3. After authorization, retry the request — credentials are now stored
4. Subsequent requests work without re-authorization

---

## For MCP Developers

Use this section if you want to **build, modify, or deploy** a Google Calendar MCP server like this one.

### Project Structure

```
src/
  main.py        # Entrypoint — loads .env and starts the server
  server.py      # MCPServer setup (port 8080, streamable HTTP)
  gcal.py        # All 29 Google Calendar tools + API connection
  _client.py     # Example client with OAuth browser flow
```

### Prerequisites

1. **Google Cloud project** with the [Calendar API](https://console.cloud.google.com/apis/library/calendar-json.googleapis.com) enabled
2. **OAuth 2.0 credentials** — create a "Web application" client in the [Google Cloud Console](https://console.cloud.google.com/apis/credentials) and download the client secret JSON
3. **Dedalus API key** (`dsk-live-*` or `dsk-test-*`)
4. [uv](https://docs.astral.sh/uv/) package manager

### Environment Variables

Copy `.env.example` and fill in your values:

```bash
cp .env.example .env
```

**OAuth configuration** (from your Google client secret JSON):

```bash
OAUTH_ENABLED=true
OAUTH_AUTHORIZE_URL=https://accounts.google.com/o/oauth2/auth
OAUTH_TOKEN_URL=https://oauth2.googleapis.com/token
OAUTH_CLIENT_ID=<your-client-id>.apps.googleusercontent.com
OAUTH_CLIENT_SECRET=GOCSPX-<your-secret>
OAUTH_SCOPES_AVAILABLE=https://www.googleapis.com/auth/calendar,https://www.googleapis.com/auth/calendar.events
OAUTH_BASE_URL=https://www.googleapis.com/calendar/v3
```

**Dedalus platform**:

```bash
DEDALUS_API_KEY=dsk-live-...
DEDALUS_API_URL=https://api.dedaluslabs.ai
DEDALUS_AS_URL=https://as.dedaluslabs.ai
```

### Adding a New Tool

1. Define an async function in `gcal.py` with the `@tool` decorator:
2. Add it to the `gcal_tools` list at the bottom of `gcal.py`

### Running Locally

```bash
cd gcal-mcp
uv sync
uv run python src/main.py
```

The server starts on **port 8080** and exposes `/mcp` via streamable HTTP.

## API Reference

- [Google Calendar API Overview](https://developers.google.com/calendar/api/guides/overview)
- [Google Calendar API Reference](https://developers.google.com/calendar/api/v3/reference)