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