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. - Google Calendar integration: Provides a bridge between Cl
Add this skill
npx mdskills install takumi0706/google-calendar-mcpComprehensive Google Calendar MCP server with OAuth2 auth, full CRUD operations, and recurring event support
1# Google Calendar MCP Server2345> **๐ VERSION UPDATE NOTICE ๐**6> Version 1.0.5 adds support for recurring events through the `recurrence` parameter in both `createEvent` and `updateEvent` tools. This allows you to create and modify recurring events directly without having to set them up manually after creation.789101112[](README.ja.md)13[](README.md)141516## Project Overview1718Google 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.1920### Core Features2122- **Google Calendar integration**: Provides a bridge between Claude Desktop and the Google Calendar API23- **MCP implementation**: Follows the Model Context Protocol specification for AI assistant tool integration24- **OAuth2 authentication**: Handles the Google API authentication flow securely25- **Event management**: Supports comprehensive calendar event operations (get, create, update, delete)26- **Color support**: Ability to set and update event colors using colorId parameter27- **STDIO transport**: Uses standard input/output for communication with Claude Desktop2829## Technical Architecture3031This project uses:3233- **TypeScript**: For type-safe code development34- **MCP SDK**: Uses `@modelcontextprotocol/sdk` for integration with Claude Desktop35- **Google API**: Uses `googleapis` for Google Calendar API access36- **Hono**: Lightweight and fast web framework for the authentication server37- **OAuth2 Providers**: Uses `@hono/oauth-providers` for PKCE-enabled OAuth2 flow38- **Zod**: Implements schema validation for request/response data39- **Environment-based configuration**: Uses dotenv for configuration management40- **AES-256-GCM**: For token encryption using Node.js crypto module41- **Open**: For automatic browser launching during authentication42- **Readline**: For manual authentication input in server environments43- **Jest**: For unit testing and coverage44- **GitHub Actions**: For CI/CD4546## Main Components47481. **MCP Server**: Core server implementation that handles communication with Claude Desktop492. **Google Calendar Tools**: Calendar operations (retrieval, creation, update, deletion)503. **Authentication Handler**: Management of OAuth2 flow with Google API514. **Schema Validation**: Ensuring data integrity in all operations525. **Token Manager**: Secure handling of authentication tokens5354## Available Tools5556This MCP server provides the following tools for interacting with Google Calendar:5758### 1. getEvents5960Retrieves calendar events with various filtering options.6162**Parameters:**63- `calendarId` (optional): Calendar ID (uses primary calendar if omitted, empty string, null, or undefined)64- `timeMin` (optional): Start time for event retrieval (ISO 8601 format, e.g., "2025-03-01T00:00:00Z"). Empty strings, null, or undefined values are ignored65- `timeMax` (optional): End time for event retrieval (ISO 8601 format). Empty strings, null, or undefined values are ignored66- `maxResults` (optional): Maximum number of events to retrieve (default: 10)67- `orderBy` (optional): Sort order ("startTime" or "updated"). Defaults to "startTime" if empty string, null, or undefined6869### 2. createEvent7071Creates a new calendar event.7273**Parameters:**74- `calendarId` (optional): Calendar ID (uses primary calendar if omitted)75- `event`: Event details object containing:76 - `summary` (required): Event title77 - `description` (optional): Event description78 - `location` (optional): Event location79 - `start`: Start time object with:80 - `dateTime` (optional): ISO 8601 format (e.g., "2025-03-15T09:00:00+09:00")81 - `date` (optional): YYYY-MM-DD format for all-day events82 - `timeZone` (optional): Time zone (e.g., "Asia/Tokyo")83 - `end`: End time object (same format as start)84 - `attendees` (optional): Array of attendees with email and optional displayName85 - `colorId` (optional): Event color ID (1-11)86 - `recurrence` (optional): Array of recurrence rules in RFC5545 format (e.g., ["RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR"])8788### 3. updateEvent8990Updates 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.9192**Parameters:**93- `calendarId` (optional): Calendar ID (uses primary calendar if omitted)94- `eventId` (required): ID of the event to update95- `event`: Event details object containing fields to update (same structure as createEvent, all fields optional)96 - Only fields that are explicitly provided will be updated97 - Fields not included in the update request will retain their existing values98 - This allows for partial updates without losing data99 - `recurrence` parameter can be updated to modify recurring event patterns100101### 4. deleteEvent102103Deletes a calendar event.104105**Parameters:**106- `calendarId` (optional): Calendar ID (uses primary calendar if omitted)107- `eventId` (required): ID of the event to delete108109### 5. authenticate110111Re-authenticates with Google Calendar. This is useful when you want to switch between different Google accounts without having to restart Claude.112113**Parameters:**114- None115116## Development Guidelines117118When adding new functions, modifying code, or fixing bugs, please semantically increase the version for each change using `npm version` command.119Also, please make sure that your coding is clear and follows all the necessary coding rules, such as OOP.120The 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.121122### Code Structure123124- **src/**: Source code directory125 - **auth/**: Authentication handling126 - **config/**: Configuration settings127 - **mcp/**: MCP server implementation128 - **tools/**: Google Calendar tool implementations129 - **utils/**: Utility functions and helpers130131### Best Practices132133- Proper typing according to TypeScript best practices134- Maintaining comprehensive error handling135- Ensure proper authentication flow136- Keep dependencies up to date137- Write clear documentation for all functions138- Implement security best practices139- Follow the OAuth 2.1 authentication standards140- Use schema validation for all input/output data141142### Testing143144- Implement unit tests for core functionality145- Thoroughly test authentication flow146- Verify calendar manipulation against Google API147- Run tests with coverage reports148- Ensure security tests are included149150## Deployment151152This package is published on npm as `@takumi0706/google-calendar-mcp`:153154```bash155npx @takumi0706/google-calendar-mcp@1.0.7156```157158### Prerequisites1591601. Create a Google Cloud Project and enable the Google Calendar API1612. Configure OAuth2 credentials in the Google Cloud Console1623. Set up environment variables:163164```bash165# Create a .env file with your Google OAuth credentials166GOOGLE_CLIENT_ID=your_client_id167GOOGLE_CLIENT_SECRET=your_client_secret168GOOGLE_REDIRECT_URI=http://localhost:4153/oauth2callback169# Optional: Token encryption key (auto-generated if not provided)170TOKEN_ENCRYPTION_KEY=32-byte-hex-key171# Optional: Auth server port and host (default port: 4153, host: localhost)172AUTH_PORT=4153173AUTH_HOST=localhost174# Optional: MCP server port and host (default port: 3000, host: localhost)175PORT=3000176HOST=localhost177# Optional: Enable manual authentication (useful when localhost is not accessible)178USE_MANUAL_AUTH=true179```180181### Claude Desktop Configuration182183Add 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".184185```json186{187 "mcpServers": {188 "google-calendar": {189 "command": "npx",190 "args": [191 "-y",192 "@takumi0706/google-calendar-mcp"193 ],194 "env": {195 "GOOGLE_CLIENT_ID": "your_client_id",196 "GOOGLE_CLIENT_SECRET": "your_client_secret",197 "GOOGLE_REDIRECT_URI": "http://localhost:4153/oauth2callback"198 }199 }200 }201}202```203204## Security Considerations205206- **OAuth tokens** are stored in memory only (not stored in a file-based storage)207- **Sensitive credentials** must be provided as environment variables208- **Token encryption** using AES-256-GCM for secure storage209- **PKCE implementation** with explicit code_verifier and code_challenge generation210- **State parameter validation** for CSRF protection211- **Rate limiting** for API endpoint protection212- **Input validation** with Zod schema213214For more details, see [SECURITY.md](SECURITY.md).215216## Maintenance217218- Regular updates to maintain compatibility with the Google Calendar API219- Version updates are documented in README.md220221## Troubleshooting222223If you encounter any issues:2242251. Make sure your Google OAuth credentials are correctly configured2262. Ensure you have sufficient permissions for Google Calendar API access2273. Verify your Claude Desktop configuration is correct228229### Common Errors230231- **JSON Parsing Errors**: If you see errors like `Unexpected non-whitespace character after JSON at position 4 (line 1 column 5)`, it's typically due to malformed JSON-RPC messages. This issue has been fixed in version 0.6.7 and later. If you're still experiencing these errors, please update to the latest version.232- **Authentication Errors**: Verify your Google OAuth credentials233- **Invalid state parameter**: If you see `Authentication failed: Invalid state parameter` when re-authenticating, update to version 1.0.3 or later which fixes the OAuth server lifecycle management. In older versions, you may need to close port 4153 and restart the application.234- **Connection Errors**: Make sure only one instance of the server is running235- **Disconnection Issues**: Ensure your server is properly handling MCP messages without custom TCP sockets236- **Cannot access localhost**: If you're running the application in an environment where localhost is not accessible (like a remote server or container), enable manual authentication by setting `USE_MANUAL_AUTH=true`. This will allow you to manually enter the authorization code shown by Google after authorizing the application.237- **MCP Parameter Validation Errors**: If you see error -32602 with empty string parameters, update to version 1.0.7 or later which handles empty strings, null, and undefined values properly.238239## Version History240241### Version 1.0.7 Changes242- Enhanced parameter validation for MCP tools to properly handle empty strings, null, and undefined values243- Fixed MCP error -32602 when empty string parameters were passed to getEvents tool244- Improved preprocessArgs function to skip empty values, allowing Zod schema defaults to be applied correctly245- Added comprehensive test coverage for empty parameter handling246247### Version 1.0.6 Changes248- Fixed the scope is not needed in this google calendar mcp server249250### Version 1.0.5 Changes251- Added support for recurring events through the `recurrence` parameter in both `createEvent` and `updateEvent` tools252- Allows creation and modification of recurring events directly without manual setup253254### Version 1.0.4 Changes255- Maintenance release with version number update256- No functional changes from version 1.0.3257- Ensures compatibility with the latest dependencies258259### Version 1.0.3 Changes260- Added new `authenticate` tool to allow re-authentication without restarting Claude261- Made it possible to switch between different Google accounts during a session262- Exposed authentication functionality through the MCP interface263- Enhanced user experience by eliminating the need to restart for account switching264- Added manual authentication option for environments where localhost is not accessible265- Implemented readline interface for entering authorization codes manually266- Added USE_MANUAL_AUTH environment variable to enable manual authentication267- Updated zod dependency to the latest version (3.24.2)268- Improved schema validation with the latest zod features269- Enhanced code stability and security270- Fixed "Invalid state parameter" error during re-authentication271- Modified OAuth server to start on-demand and shut down after authentication272- Improved server lifecycle management to prevent port conflicts273- Enhanced error handling for authentication flow274275### Version 1.0.2 Changes276- Fixed `updateEvent` function to preserve existing event data when performing partial updates277- Added `getEvent` function to fetch existing event data before updating278- Modified `updateEvent` to merge update data with existing data to prevent data loss279- Updated schema validation to make all fields optional in update requests280- Improved documentation for the `updateEvent` function281282### Version 1.0.1 Changes283- Fixed compatibility issue with Node.js v20.9.0+ and the 'open' package (v10+)284- Replaced static import with dynamic import for the ESM-only 'open' package285- Improved error handling for browser opening during OAuth authentication286- Enhanced code comments for better maintainability287288### Version 1.0.0 Changes289- Major version release marking production readiness290- Comprehensive code refactoring for improved maintainability291- Internationalization of all messages and comments (translated Japanese to English)292- Enhanced code consistency and readability293- Improved error messages for better user experience294- Updated documentation to reflect current state of the project295- Standardized coding style throughout the codebase296297### Version 0.8.0 Changes298- Enhanced OAuth authentication flow to handle refresh token issues299- Added `prompt: 'consent'` parameter to force Google to show the consent screen and provide a new refresh token300- Modified authentication flow to work with just an access token if a refresh token is not available301- Improved token refresh logic to handle cases where there's no refresh token or if the refresh token is invalid302- Updated token storage to save refreshed access tokens for better token management303- Fixed potential infinite loop in token refresh logic304305## Installation306307### Quick Start (Recommended)308309Install directly from npm:310311```bash312npm install -g @takumi0706/google-calendar-mcp313```314315### Manual Installation316317For development or customization:318319```bash320# Clone the repository321git clone https://github.com/takumi0706/google-calendar-mcp.git322cd google-calendar-mcp323324# Install dependencies325npm install326327# Build the project328npm run build329330# Run the server331npm start332```333334## Production Deployment335336For production use, the server requires valid Google OAuth credentials. The server will fail to start without proper credentials, ensuring security compliance.337338## Testing339340To run the tests:341342```bash343# Run all tests344npm test345346# Run tests with coverage report347npm test -- --coverage348```349350## License351352MIT353
Full transparency โ inspect the skill content before installing.