Google Calendar Integration for Claude Desktop

Overview

The Google Calendar MCP Server is an implementation of the Model Context Protocol (MCP) that enables seamless integration between Google Calendar and Claude Desktop. This project allows users to interact with their Google Calendar through natural language commands, facilitating event management directly within Claude Desktop.

Core Features

• Google Calendar Integration: Bridges Claude Desktop with the Google Calendar API.
• MCP Implementation: Adheres to the Model Context Protocol for AI assistant tool integration.
• OAuth2 Authentication: Securely handles Google API authentication.
• Event Management: Supports event retrieval, creation, updates, and deletions.
• Color Support: Allows setting and updating event colors using colorId.
• Multi-Transport Support: Supports both STDIO and HTTP transports simultaneously.

Technical Architecture

This project is built using:
- TypeScript: Ensures type-safe code development.
- MCP SDK: Facilitates integration with Claude Desktop.
- Google API: Provides access to Google Calendar.
- Zod: Implements schema validation for data integrity.
- Express: Powers the HTTP server implementation.
- Helmet.js: Enhances security with HTTP headers.
- AES-256-GCM: Secures token encryption.
- Jest: Manages unit testing and coverage.
- GitHub Actions: Automates CI/CD processes.

Main Components

1. MCP Server: Handles communication with Claude Desktop.
2. Google Calendar Tools: Manages calendar operations (retrieval, creation, updates, deletions).
3. Authentication Handler: Manages the OAuth2 flow with Google API.
4. Schema Validation: Ensures data integrity in all operations.
5. HTTP/JSON Transport: Provides additional connectivity options.
6. Token Manager: Securely handles authentication tokens.

Available Tools

1. getEvents

Retrieves calendar events with filtering options.

Parameters:
- calendarId (optional): Calendar ID (defaults to primary calendar).
- timeMin (optional): Start time for event retrieval (ISO 8601 format).
- timeMax (optional): End time for event retrieval (ISO 8601 format).
- maxResults (optional): Maximum number of events to retrieve (default: 10).
- orderBy (optional): Sort order ("startTime" or "updated").

2. createEvent

Creates a new calendar event.

Parameters:
- calendarId (optional): Calendar ID (defaults to primary calendar).
- event: Event details object containing:
- summary (required): Event title.
- description (optional): Event description.
- location (optional): Event location.
- start: Start time object with dateTime, date, and timeZone.
- 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).

3. updateEvent

Updates an existing calendar event.

Parameters:
- calendarId (optional): Calendar ID (defaults to primary calendar).
- eventId (required): ID of the event to update.
- event: Event details object containing fields to update.

4. deleteEvent

Deletes a calendar event.

Parameters:
- calendarId (optional): Calendar ID (defaults to primary calendar).
- eventId (required): ID of the event to delete.

Configuration

Prerequisites

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 in a .env file:

GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_REDIRECT_URI=http://localhost:3000/oauth2callback
TOKEN_ENCRYPTION_KEY=32-byte-hex-key

Claude Desktop Configuration

Add the server to your claude_desktop_config.json:

{
  "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:3000/oauth2callback"
      }
    }
  }
}

Security Considerations

• OAuth Tokens: Stored in memory only.
• Sensitive Credentials: Provided as environment variables.
• Token Encryption: Uses AES-256-GCM for secure storage.
• PKCE Implementation: Protects against authorization code interception.
• State Parameter Validation: Prevents CSRF attacks.
• Security Headers: Applied using Helmet.js.
• Rate Limiting: Protects API endpoints from abuse.

Version History

Version 0.8.0 Changes

• Enhanced OAuth authentication flow to handle refresh token issues.
• Added prompt: 'consent' parameter for better token management.
• Improved token refresh logic and storage.

Version 0.7.0 Changes

• Fixed OAuth callback handling issues.
• Improved compatibility with different OAuth configurations.

Version 0.6.9 Changes

• Fixed OAuth authentication prompt issues.
• Enhanced token refresh mechanism.

Version 0.6.8 Changes

• Resolved port conflict issues.
• Improved version management and server procedures.

Version 0.6.7 Changes

• Fixed critical JSON parsing bugs.
• Improved logging and message handling.

Development

Setup

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

Testing

npm test
npm test -- --coverage

License

MIT