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 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 enabled
2. OAuth 2.0 credentials — create a "Web application" client in the Google Cloud Console and download the client secret JSON
3. Dedalus API key (dsk-live-* or dsk-test-*)
4. uv package manager

Environment Variables

Copy .env.example and fill in your values:

cp .env.example .env

OAuth configuration (from your Google client secret JSON):

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:

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

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
• Google Calendar API Reference