takumi0706/google-calendar-mcp

> **🔔 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.