@promota-ai/google-calendar

Promota.ai MCP connector for Google Calendar. Exposes CRUD tools (list, get, create, update, delete) over the Model Context Protocol.

Requirements

• Node.js 20+
• A Google Cloud project with the Google Calendar API enabled
• OAuth 2.0 credentials downloaded as gcp-oauth.keys.json

Setup

1. Create OAuth credentials

1. Go to Google Cloud Console → APIs & Services → Credentials.
2. Create an OAuth client ID (type: Desktop app).
3. Download the JSON file and save it as gcp-oauth.keys.json in the package root (or any ancestor directory, or set GCAL_OAUTH_KEYS_PATH).

2. Requested OAuth scopes

| Scope | Purpose | |-------|---------| | https://www.googleapis.com/auth/calendar | Full calendar read/write |

Tip: If you only need read access, swap for calendar.events.readonly and calendar.readonly and update SCOPES in src/auth.ts.

3. Authenticate

npm run auth

This opens a browser, runs the OAuth consent flow, and saves the token to ~/.google-calendar-mcp/credentials.json with 0600 permissions.

To use a custom port (e.g. when port 8080 is in use):

GCAL_OAUTH_PORT=9090 npm run auth

Environment Variables

| Variable | Default | Purpose | |----------|---------|---------| | GCAL_OAUTH_KEYS_PATH | (ancestor walk for gcp-oauth.keys.json) | Path to the GCP credentials file | | GCAL_TOKEN_PATH | ~/.google-calendar-mcp/credentials.json | Where the OAuth token is stored | | GCAL_OAUTH_PORT | 8080 | Local callback port for the OAuth flow |

Running the MCP server

npm run build
npm start

Or in development:

node dist/index.js

MCP Tools

| Tool | Required args | Optional args | |------|--------------|---------------| | list_calendars | — | — | | list_events | calendar_id | time_min, time_max, max_results (≤50), query | | get_event | calendar_id, event_id | — | | create_event | calendar_id, summary, start, end | description, location, attendees, timezone, send_notifications | | update_event | calendar_id, event_id | summary, description, location, start, end, attendees, timezone, send_notifications | | delete_event | calendar_id, event_id | send_notifications (default false) |

Note: delete_event defaults send_notifications to false — attendees are NOT emailed on deletion unless you explicitly pass send_notifications: true.

Local development with cloudflared

For OAuth callbacks from a remote tunnel (e.g. devel-stage):

cloudflared tunnel --url http://localhost:8080

Register the resulting https://…trycloudflare.com URL as an authorized redirect URI in your GCP OAuth client settings.

Testing

npm test              # run once
npm run test:watch    # watch mode
npm run coverage      # with v8 coverage report

Token refresh

Tokens refresh automatically via googleapis event listener. Refreshed credentials are written back to GCAL_TOKEN_PATH with 0600 permissions. If a token becomes invalid mid-session, the connector resets and surfaces Not authenticated. Run: npm run auth.