Google Calendar MCP Server

A Model Context Protocol (MCP) server that provides Google Calendar integration for AI assistants like Claude.

Features

• Multi-Calendar Support: List events from multiple calendars simultaneously
• Event Management: Create, update, delete, and search calendar events
• Recurring Events: Advanced modification capabilities for recurring events
• Free/Busy Queries: Check availability across calendars
• Smart Scheduling: Natural language understanding for dates and times
• Intelligent Import: Add calendar events from images, PDFs or web links

Authentication

This MCP server uses external token authentication. You need to provide:

1. A valid Google OAuth2 access token
2. The granted scopes for that token

For stdio mode (Claude Desktop):

• Set OPPIE_ACCESS_TOKEN environment variable with your Google OAuth access token
• Set OPPIE_GRANTED_SCOPES environment variable with the granted scopes

For HTTP mode:

• Send x-env-oppie-access-token header with your Google OAuth access token
• Send x-env-oppie-granted-scopes header with the granted scopes

Scopes can be provided in any of these formats:

• JSON array: ["https://www.googleapis.com/auth/calendar", "https://www.googleapis.com/auth/calendar.events"]
• Space-separated: https://www.googleapis.com/auth/calendar https://www.googleapis.com/auth/calendar.events
• Comma-separated: https://www.googleapis.com/auth/calendar,https://www.googleapis.com/auth/calendar.events

Quick Start

Option 1: Use with Claude Desktop (stdio mode)

Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      "args": ["@oppie-ai/mcp-google-calendar"],
      "env": {
        "OPPIE_ACCESS_TOKEN": "your-google-oauth-access-token",
        "OPPIE_GRANTED_SCOPES": "https://www.googleapis.com/auth/calendar https://www.googleapis.com/auth/calendar.events"
      }
    }
  }
}

Option 2: Local Installation

git clone https://github.com/OppieAI/google-calendar-mcp.git
cd google-calendar-mcp
npm install
npm run build

# For stdio mode:
export OPPIE_ACCESS_TOKEN="your-google-oauth-access-token"
export OPPIE_GRANTED_SCOPES="https://www.googleapis.com/auth/calendar https://www.googleapis.com/auth/calendar.events"
npm start

# For HTTP mode (default):
npm start
# Server will run on http://localhost:8080
# Send required headers with each request

Option 3: Docker Installation (HTTP mode)

# Using Docker Hub image
docker run -p 8080:8080 oppieai/mcp-google-calendar

# Or build locally
git clone https://github.com/OppieAI/google-calendar-mcp.git
cd google-calendar-mcp
docker compose up

The Docker container runs in HTTP mode on port 8080. You must include authentication headers with each request:

• x-env-oppie-access-token: Your Google OAuth access token
• x-env-oppie-granted-scopes: The granted scopes

Example:

curl -X POST http://localhost:8080 \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "x-env-oppie-access-token: your-token" \
  -H "x-env-oppie-granted-scopes: https://www.googleapis.com/auth/calendar https://www.googleapis.com/auth/calendar.events" \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}'

Available Tools

Calendar Management

• list-calendars - List all calendars
• list-colors - List available calendar colors

Event Operations

• list-events - List events with flexible filtering
  • Multiple calendar support
  • Time range filtering
  • Timezone handling
• search-events - Full-text search across events
• create-event - Create new events with:
  • All-day or timed events
  • Recurring events
  • Attendees and notifications
  • Video conferencing
• update-event - Update existing events
• delete-event - Delete events (with recurring event options)

Scheduling

• free-busy - Check availability across calendars
• get-current-time - Get current time in any timezone

Import Events

• add-event-from-image - Extract and create events from images
• add-event-from-pdf - Extract and create events from PDFs
• add-event-from-url - Create events from web content

Development

Running Tests

npm test                    # Unit tests
npm run test:integration    # Integration tests

Debug Mode

# Enable debug logging
DEBUG=true npm start

# Or in Docker
docker run -p 8080:8080 -e DEBUG=true oppieai/mcp-google-calendar

HTTP Mode Endpoints

• GET /health - Health check endpoint
• POST / - MCP protocol endpoint (requires authentication headers)

Configuration

Environment Variables

• OPPIE_ACCESS_TOKEN - Google OAuth access token (stdio mode)
• OPPIE_GRANTED_SCOPES - Granted OAuth scopes (stdio mode)
• DEBUG - Enable debug logging (true/false)
• TRANSPORT - Transport mode: stdio or http (default: http)
• PORT - HTTP server port (default: 8080)
• HOST - HTTP server host (default: 127.0.0.1)

Docker Configuration

The Docker setup always runs in HTTP mode. Configure via environment variables:

environment:
  DEBUG: true
  PORT: 8080
  HOST: 0.0.0.0

Troubleshooting

Authentication Issues

• Ensure your access token is valid and not expired
• Verify the token has the required calendar scopes
• Check that headers are being sent correctly (for HTTP mode)

Connection Issues

• For HTTP mode: Check that the Accept header includes both application/json and text/event-stream
• Verify the server is running on the expected port
• Check firewall/network settings

Debug Logging

Enable debug mode to see detailed logs:

DEBUG=true npm start

License

MIT License - see LICENSE file for details