Provides event management capabilities for Google Calendar, allowing retrieval, creation, updating, and deletion of calendar events through the Google Calendar API with OAuth2 authentication
Google Calendar MCP Server
🔔 VERSION UPDATE NOTICE 🔔
Version 1.0.5 adds support for recurring events through therecurrence
parameter in bothcreateEvent
andupdateEvent
tools. This allows you to create and modify recurring events directly without having to set them up manually after creation.
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/sdk
for integration with Claude DesktopGoogle API: Uses
googleapis
for Google Calendar API accessZod: Implements schema validation for request/response data
Environment-based configuration: Uses dotenv for configuration management
Helmet.js: For security headers
AES-256-GCM: For token encryption
Jest: For unit testing and coverage
GitHub Actions: For CI/CD
Main Components
MCP Server: Core server implementation that handles communication with Claude Desktop
Google Calendar Tools: Calendar operations (retrieval, creation, update, deletion)
Authentication Handler: Management of OAuth2 flow with Google API
Schema Validation: Ensuring data integrity in all operations
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)timeMin
(optional): Start time for event retrieval (ISO 8601 format, e.g., "2025-03-01T00:00:00Z")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 (uses primary calendar if omitted)event
: Event details object containing:summary
(required): Event titledescription
(optional): Event descriptionlocation
(optional): Event locationstart
: 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 eventstimeZone
(optional): Time zone (e.g., "Asia/Tokyo")
end
: End time object (same format as start)attendees
(optional): Array of attendees with email and optional displayNamecolorId
(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 updateevent
: 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
config/: Configuration settings
mcp/: MCP server implementation
tools/: Google Calendar tool implementations
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
:
Prerequisites
Create a Google Cloud Project and enable the Google Calendar API
Configure OAuth2 credentials in the Google Cloud Console
Set up environment variables:
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".
Security Considerations
OAuth tokens are stored in memory only (not stored in a file-based storage)
Sensitive credentials must be provided as environment variables
Token encryption using AES-256-GCM for secure storage
PKCE implementation with explicit code_verifier and code_challenge generation
State parameter validation for CSRF protection
Security headers applied using Helmet.js
Rate limiting for API endpoint protection
Input validation with Zod schema
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:
Make sure your Google OAuth credentials are correctly configured
Ensure you have sufficient permissions for Google Calendar API access
Verify your Claude Desktop configuration is correct
Common Errors
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.Authentication Errors: Verify your Google OAuth credentials
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.Connection Errors: Make sure only one instance of the server is running
Disconnection Issues: Ensure your server is properly handling MCP messages without custom TCP sockets
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.
Version History
Version 1.0.6 Changes
Fixed the scope is not needed in this google calendar mcp server
Version 1.0.5 Changes
Added support for recurring events through the
recurrence
parameter in bothcreateEvent
andupdateEvent
toolsAllows creation and modification of recurring events directly without manual setup
Version 1.0.4 Changes
Maintenance release with version number update
No functional changes from version 1.0.3
Ensures compatibility with the latest dependencies
Version 1.0.3 Changes
Added new
authenticate
tool to allow re-authentication without restarting ClaudeMade it possible to switch between different Google accounts during a session
Exposed authentication functionality through the MCP interface
Enhanced user experience by eliminating the need to restart for account switching
Added manual authentication option for environments where localhost is not accessible
Implemented readline interface for entering authorization codes manually
Added USE_MANUAL_AUTH environment variable to enable manual authentication
Updated zod dependency to the latest version (3.24.2)
Improved schema validation with the latest zod features
Enhanced code stability and security
Fixed "Invalid state parameter" error during re-authentication
Modified OAuth server to start on-demand and shut down after authentication
Improved server lifecycle management to prevent port conflicts
Enhanced error handling for authentication flow
Version 1.0.2 Changes
Fixed
updateEvent
function to preserve existing event data when performing partial updatesAdded
getEvent
function to fetch existing event data before updatingModified
updateEvent
to merge update data with existing data to prevent data lossUpdated schema validation to make all fields optional in update requests
Improved documentation for the
updateEvent
function
Version 1.0.1 Changes
Fixed compatibility issue with Node.js v20.9.0+ and the 'open' package (v10+)
Replaced static import with dynamic import for the ESM-only 'open' package
Improved error handling for browser opening during OAuth authentication
Enhanced code comments for better maintainability
Version 1.0.0 Changes
Major version release marking production readiness
Comprehensive code refactoring for improved maintainability
Internationalization of all messages and comments (translated Japanese to English)
Enhanced code consistency and readability
Improved error messages for better user experience
Updated documentation to reflect current state of the project
Standardized coding style throughout the codebase
Version 0.8.0 Changes
Enhanced OAuth authentication flow to handle refresh token issues
Added
prompt: 'consent'
parameter to force Google to show the consent screen and provide a new refresh tokenModified authentication flow to work with just an access token if a refresh token is not available
Improved token refresh logic to handle cases where there's no refresh token or if the refresh token is invalid
Updated token storage to save refreshed access tokens for better token management
Fixed potential infinite loop in token refresh logic
Development
To contribute to this project:
Testing
To run the tests:
License
MIT
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
A Model Context Protocol server that integrates Google Calendar with Claude Desktop, enabling users to manage calendar events (view, create, update, delete) through natural language.
Related MCP Servers
- AsecurityAlicenseAqualityModel Context Protocol server for Gmail integration. This allows Claude Desktop (or any MCP client) to interact with your Gmail account through Google Apps Script.Last updated -2612MIT License
- -securityAlicense-qualityEnables comprehensive calendar management with capabilities to create, list, update, and delete events through a Model Context Protocol server integrated with Google Calendar.Last updated -143MIT License
- -securityFlicense-qualityAllows interaction with Google Calendar through Claude Desktop using the Model Context Protocol, enabling calendar event management and schedule analysis.Last updated -2
- -securityFlicense-qualityModel Context Protocol server that provides seamless access to Google Calendar API with asynchronous operation support, enabling efficient calendar management through a standardized interface.Last updated -1