Google Calendar MCP Server

🔔 VERSION UPDATE NOTICE 🔔
Version 2.0.0 moves to MCP protocol revision 2026-07-28 and implements PKCE on the OAuth flow. It requires Node.js 20 or newer. See the version history below for the full list of changes.

Project Overview

Google Calendar MCP Server is an MCP (Model Context Protocol) server implementation that enables integration between Google Calendar and Claude Desktop. This project enables Claude to interact with the user's Google Calendar, providing the ability to display, create, update, and delete calendar events through natural language interaction.

Core Features

• Google Calendar integration: Provides a bridge between Claude Desktop and the Google Calendar API
• MCP implementation: Follows the Model Context Protocol specification for AI assistant tool integration
• OAuth2 authentication: Handles the Google API authentication flow securely
• Event management: Supports comprehensive calendar event operations (get, create, update, delete)
• Color support: Ability to set and update event colors using colorId parameter
• STDIO transport: Uses standard input/output for communication with Claude Desktop

Technical Architecture

This project uses:

• TypeScript: For type-safe code development
• MCP SDK: Uses @modelcontextprotocol/server v2 (protocol revision 2026-07-28, with the 2025 revisions still served for older clients)
• Google API: Uses googleapis for Google Calendar API access
• Hono: Lightweight and fast web framework for the authentication server
• google-auth-library: Drives the OAuth2 authorization code flow with PKCE (S256)
• Zod: Implements schema validation for request/response data
• Environment-based configuration: Uses dotenv for configuration management
• AES-256-GCM: For token encryption using Node.js crypto module
• Open: For automatic browser launching during authentication
• Readline: For manual authentication input in server environments
• Jest: For unit testing and coverage
• GitHub Actions: For CI/CD

Main Components

1. MCP Server: Core server implementation that handles communication with Claude Desktop
2. Google Calendar Tools: Calendar operations (retrieval, creation, update, deletion)
3. Authentication Handler: Management of OAuth2 flow with Google API
4. Schema Validation: Ensuring data integrity in all operations
5. Token Manager: Secure handling of authentication tokens

Available Tools

This MCP server provides the following tools for interacting with Google Calendar:

1. getEvents

Retrieves calendar events with various filtering options.

Parameters:

• calendarId (optional): Calendar ID (uses primary calendar if omitted, empty string, null, or undefined)
• timeMin (optional): Start time for event retrieval (ISO 8601 format, e.g., "2025-03-01T00:00:00Z"). Empty strings, null, or undefined values are ignored
• timeMax (optional): End time for event retrieval (ISO 8601 format). Empty strings, null, or undefined values are ignored
• maxResults (optional): Maximum number of events to retrieve (default: 10)
• orderBy (optional): Sort order ("startTime" or "updated"). Defaults to "startTime" if empty string, null, or undefined

2. createEvent

Creates a new calendar event.

Parameters:

• calendarId (optional): Calendar ID (uses primary calendar if omitted)
• event: Event details object containing:
  • summary (required): Event title
  • description (optional): Event description
  • location (optional): Event location
  • start: Start time object with:
    • dateTime (optional): ISO 8601 format (e.g., "2025-03-15T09:00:00+09:00")
    • date (optional): YYYY-MM-DD format for all-day events
    • timeZone (optional): Time zone (e.g., "Asia/Tokyo")
  • end: End time object (same format as start)
  • attendees (optional): Array of attendees with email and optional displayName
  • colorId (optional): Event color ID (1-11)
  • recurrence (optional): Array of recurrence rules in RFC5545 format (e.g., ["RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR"])

3. updateEvent

Updates an existing calendar event. The function fetches the existing event data first and merges it with the update data, preserving fields that are not included in the update request.

Parameters:

• calendarId (optional): Calendar ID (uses primary calendar if omitted)
• eventId (required): ID of the event to update
• event: Event details object containing fields to update (same structure as createEvent, all fields optional)
  • Only fields that are explicitly provided will be updated
  • Fields not included in the update request will retain their existing values
  • This allows for partial updates without losing data
  • recurrence parameter can be updated to modify recurring event patterns

4. deleteEvent

Deletes a calendar event.

Parameters:

• calendarId (optional): Calendar ID (uses primary calendar if omitted)
• eventId (required): ID of the event to delete

5. authenticate

Re-authenticates with Google Calendar. This is useful when you want to switch between different Google accounts without having to restart Claude.

Parameters:

• None

Development Guidelines

When adding new functions, modifying code, or fixing bugs, please semantically increase the version for each change using npm version command. Also, please make sure that your coding is clear and follows all the necessary coding rules, such as OOP. The version script will automatically run npm install when the version is updated, but you should still build, run lint, and test your code before submitting it.

Code Structure

• src/: Source code directory
  • auth/: Authentication handling (OAuth flow with PKCE, token storage)
  • calendar/: Google Calendar API integration
  • config/: Configuration settings and validation
  • mcp/: MCP server implementation
    • tools/: Google Calendar tool handlers
  • utils/: Utility functions and helpers

Best Practices

• Proper typing according to TypeScript best practices
• Maintaining comprehensive error handling
• Ensure proper authentication flow
• Keep dependencies up to date
• Write clear documentation for all functions
• Implement security best practices
• Follow the OAuth 2.1 authentication standards
• Use schema validation for all input/output data

Testing

• Implement unit tests for core functionality
• Thoroughly test authentication flow
• Verify calendar manipulation against Google API
• Run tests with coverage reports
• Ensure security tests are included

Deployment

This package is published on npm as @takumi0706/google-calendar-mcp:

npx @takumi0706/google-calendar-mcp@2.0.0

Prerequisites

0. Node.js 20 or newer
1. Create a Google Cloud Project and enable the Google Calendar API
2. Configure OAuth2 credentials in the Google Cloud Console
3. Set up environment variables:

# Create a .env file with your Google OAuth credentials
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_REDIRECT_URI=http://localhost:4153/oauth2callback
# Optional: Token encryption key (auto-generated if not provided)
TOKEN_ENCRYPTION_KEY=32-byte-hex-key
# Optional: Auth server port and host (default port: 4153, host: localhost)
AUTH_PORT=4153
AUTH_HOST=localhost
# Optional: MCP server port and host (default port: 3000, host: localhost)
PORT=3000
HOST=localhost
# Optional: Enable manual authentication (useful when localhost is not accessible)
USE_MANUAL_AUTH=true

Claude Desktop Configuration

Add the server to your claude_desktop_config.json. If you're running in an environment where localhost is not accessible, add the USE_MANUAL_AUTH environment variable set to "true".

{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      "args": [
        "-y",
        "@takumi0706/google-calendar-mcp"
      ],
      "env": {
        "GOOGLE_CLIENT_ID": "your_client_id",
        "GOOGLE_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_REDIRECT_URI": "http://localhost:4153/oauth2callback"
      }
    }
  }
}

Security Considerations

• OAuth tokens are stored in memory only (not stored in a file-based storage). They are lost on restart, which means re-authentication is required after every restart.
• Sensitive credentials must be provided as environment variables
• Token encryption using AES-256-GCM while tokens sit in memory. Note that the key lives in the same process as the ciphertext, so this protects against casual inspection of process memory, not against an attacker who can already read this process's memory.
• PKCE (S256) on the authorization code flow, with a code_verifier generated per request and never sent to the authorization endpoint
• State parameter validation for CSRF protection: 256-bit CSPRNG state, compared in constant time, single-use, and expiring after 10 minutes
• Fixed redirect URI taken from configuration rather than from the request's Host header
• Input validation with Zod schema
• HTML escaping on every value interpolated into the OAuth result pages

For more details, see SECURITY.md.

Maintenance

• Regular updates to maintain compatibility with the Google Calendar API
• Version updates are documented in README.md

Troubleshooting

If you encounter any issues: