google-calendar-streamable

This MCP server provides a streamable HTTP interface to Google Calendar, enabling you to search across all calendars, create and update events, delete events, check availability, and schedule meetings. It exposes a REST/HTTP API via an MCP-compatible surface that your client (such as Claude Desktop or Cursor) can interact with. The server also supports natural language capabilities for event creation (e.g., parsing phrases like 'Lunch tomorrow at noon' into calendar events) and automatically creates Google Meet links for new events. It relies on OAuth 2.1 with PKCE to securely connect to your Google Calendar data and can run in two environments: a local Node/Hono setup and a remote Cloudflare Worker deployment for remote access. To use it locally, you’ll typically run the server (via Bun) and point your MCP client at the localhost path /mcp.

Key capabilities include:

• Events: search, create, update, delete, respond to invitations
• Calendars: discover available calendars
• Availability: check free/busy for scheduling
• Natural Language: create events from text commands
• Google Meet: auto-create Meet links for events
• OAuth 2.1 with PKCE: secure authorization flow
• Dual Runtime: Node/Bun for local use or Cloudflare Worker for remote use

To connect your MCP client, configure the client to target http://localhost:3000/mcp (or the deployed URL from Cloudflare) and use the transport option that suits your environment (http-only for simple setups). The client configuration typically looks like the examples in the README, where you define an mcpServers entry with the command and arguments to run the MCP surface locally or remotely.

Prerequisites

• Bun installed (https://bun.sh)
• Node.js 20+ (https://nodejs.org)
• A Google Cloud project with Calendar API enabled (for OAuth)
• Optional: Cloudflare account if you plan to deploy as a Worker

Step-by-step installation

1. Clone the repository and install dependencies

git clone <repo-url>
cd google-calendar-mcp
bun install

2. Prepare environment and credentials

• Copy example env and update values

cp env.example .env

• Edit .env to enable OAuth and provide your Google client details (client_id, client_secret), OAuth scopes, and redirect URI as shown in the README. Example values:

PORT=3000
AUTH_ENABLED=true

PROVIDER_CLIENT_ID=your_client_id
PROVIDER_CLIENT_SECRET=your_client_secret

OAUTH_SCOPES=https://www.googleapis.com/auth/calendar.events https://www.googleapis.com/auth/calendar.readonly
OAUTH_REDIRECT_URI=http://127.0.0.1:3001/oauth/callback
OAUTH_REDIRECT_ALLOWLIST=alice://oauth/callback,http://127.0.0.1:3001/oauth/callback

3. Run the MCP server locally

bun dev

• The MCP endpoint will be available at: http://127.0.0.1:3000/mcp
• The OAuth authorization UI will be at: http://127.0.0.1:3001

4. (Optional) Cloudflare Worker deployment

• Follow the Cloudflare deployment steps in the README to deploy the Worker and set up KV storage, secrets, and redirect URIs.
• The remote MCP endpoint will be something like: https://<worker-name>.<account>.workers.dev/mcp

5. Client configuration

• For Claude Desktop / Cursor, configure mcpServers with the appropriate command and transport as shown in the README (local or remote).

Tips and notes:

• The OAuth flow is designed for development convenience. For production, harden security with proper token validation, TLS termination, CORS/origin checks, rate limiting, and audit logging.
• If you’re using Cloudflare Workers, consider enabling token encryption for OAuth tokens in KV (TOKENS_ENC_KEY) and using a KV namespace to store tokens securely.
• The default MCP surface searches all calendars by default (search_events). Be mindful of permissions and calendar visibility when sharing access.
• If you encounter Node version issues in client tools, you may need to specify an explicit node path as shown in the README (NVM path workaround).
• If you’re testing locally, you can pre-authenticate with Claude Desktop to avoid short OAuth timeouts.
• The server exposes endpoints under /mcp; ensure your firewall or host allows traffic to this path during testing.
• When using the Natural Language feature, provide clear phrases that map to events to minimize model hallucinations. Always verify actions like updates or deletions through the MCP client.