GCAL-MCP

A Dedalus MCP server for read-only access to the Google Calendar API v3.

Setup

1. Create Google OAuth credentials (one-time)

• Go to the Google Cloud Console

• Create/select a project

• Enable Google Calendar API

• Configure OAuth consent screen

  • If in testing mode: add your Google account as a Test user

• Create an OAuth client ID

  • Application type: Desktop app

  • Download the JSON (OAuth client credentials)

2. Copy .env.example to .env and set your credentials path:

3. Install dependencies:

4. Authenticate once (opens browser and stores tokens locally):

5. Run the server:

Available Tools

Calendars

• gcal_list_calendars - List all calendars accessible by the user

• gcal_get_calendar - Get details of a specific calendar

Events

• gcal_list_events - List events from a calendar with date filtering

• gcal_get_event - Get details of a specific event by ID

• gcal_search_events - Search events by text query

• gcal_get_event_instances - Get instances of a recurring event

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

Authentication

This server uses Google OAuth Bearer tokens. Recommended flow:

• Provide your OAuth client JSON via GOOGLE_OAUTH_CREDENTIALS

• Run uv run python -m src.gcal_auth once

• Tokens will be saved to ~/.config/gcal-mcp/tokens.json (configurable) and auto-refreshed

Note: This provides read-only access to calendar data. Write operations (creating, updating, deleting events) are not currently supported in this read-only implementation.

Getting an Access Token

gcal-mcp will obtain and refresh access tokens for you via the installed-app OAuth flow.

If you need the exact scope(s), default is:

• https://www.googleapis.com/auth/calendar.readonly

Token Refresh

Access tokens expire (typically after ~1 hour) but this repo will refresh them automatically if a refresh token was issued.

If you ever need to re-authenticate, run:

Relevant environment variables

• GOOGLE_OAUTH_CREDENTIALS: Path to downloaded OAuth client JSON (Desktop app)

• GCAL_TOKEN_PATH (optional): Token file location (default ~/.config/gcal-mcp/tokens.json)

• GCAL_SCOPES (optional): Comma-separated scopes (default is read-only)

• GCAL_ACCESS_TOKEN (optional/manual): If set, overrides all other auth logic

API Rate Limits

Google Calendar API has quota limits. See Google Calendar API Quotas for details.

Default limits:

• 1,000,000 queries per day

• 500 queries per 100 seconds per user

Example Usage

List all calendars

List events for the next week

Search for events

Check availability

License

MIT