-
securityA
license-
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 -
14
3
MIT License
Provides comprehensive Google Calendar integration, enabling listing, creating, updating, and deleting calendar events, as well as retrieving available calendars with various filtering options.
Integrates with Google Cloud for authentication and access control through service accounts and OAuth, enabling secure access to Google Calendar API resources.
Google Calendar MCP Server
A Model Context Protocol (MCP) server that provides comprehensive Google Calendar integration capabilities. This server allows AI assistants and applications to interact with Google Calendar through a standardized protocol.
Features
List Events: Retrieve events from Google Calendar with filtering options
Create Events: Create new calendar events with full customization
Update Events: Modify existing calendar events
Delete Events: Remove events from calendars
List Calendars: Get available calendars for the authenticated user
OAuth Authentication: Secure Google Calendar API access
Tools Available
list_events
Retrieve events from a Google Calendar with various filtering options.
Parameters:
calendarId(optional): Calendar ID (default: "primary")timeMin(optional): Lower bound for event start time (RFC3339 timestamp)timeMax(optional): Upper bound for event start time (RFC3339 timestamp)maxResults(optional): Maximum number of events (default: 250)singleEvents(optional): Expand recurring events (default: true)orderBy(optional): Order events by "startTime" or "updated"
create_event
Create a new event in Google Calendar.
Parameters:
calendarId(optional): Calendar ID (default: "primary")summary(required): Event titledescription(optional): Event descriptionstart(required): Start date/time object with dateTime and optional timeZoneend(required): End date/time object with dateTime and optional timeZonelocation(optional): Event locationattendees(optional): Array of attendee objects with email and displayNamerecurrence(optional): Array of RRULE strings for recurring events
update_event
Update an existing calendar event.
Parameters:
calendarId(optional): Calendar ID (default: "primary")eventId(required): ID of the event to updatesummary(optional): New event titledescription(optional): New event descriptionstart(optional): New start date/timeend(optional): New end date/timelocation(optional): New event locationattendees(optional): New attendees list
delete_event
Delete an event from Google Calendar.
Parameters:
calendarId(optional): Calendar ID (default: "primary")eventId(required): ID of the event to delete
list_calendars
List available Google Calendars for the authenticated user.
Parameters:
minAccessRole(optional): Minimum access role filtershowDeleted(optional): Include deleted calendars (default: false)showHidden(optional): Include hidden calendars (default: false)
Setup
Prerequisites
Google Cloud Project: Create a project in Google Cloud Console
Enable Google Calendar API: Enable the Calendar API for your project
Service Account: Create a service account and download the JSON key file
Installation
Clone this repository
Install dependencies:
npm installCopy the environment file and configure:
copy .env.example .envEdit
.envand set your Google Service Account key file path:GOOGLE_SERVICE_ACCOUNT_KEY_FILE=./path/to/your/service-account-key.json
Building
# Build the TypeScript code
npm run build
# Development mode with hot reload
npm run dev
# Type checking
npm run type-check
# Clean build artifacts
npm run clean
Usage
Running the Server
# Start the compiled server
npm start
# Or run in development mode
npm run dev
Integrating with MCP Clients
Add this server to your MCP client configuration:
{
"servers": {
"google-calendar": {
"type": "stdio",
"command": "node",
"args": ["./dist/index.js"]
}
}
}
For VS Code with MCP extension, add to .vscode/mcp.json:
{
"servers": {
"google-calendar-mcp-server": {
"type": "stdio",
"command": "node",
"args": ["./dist/index.js"]
}
}
}
Authentication Setup
Create a Service Account:
Go to Google Cloud Console
Navigate to IAM & Admin > Service Accounts
Create a new service account
Download the JSON key file
Share Calendar Access:
Open Google Calendar
Go to calendar settings
Share your calendar with the service account email
Grant "Make changes to events" permission
Configure Environment:
Place the JSON key file in your project directory
Update the
.envfile with the correct path
Development
Project Structure
src/
├── index.ts # Main MCP server implementation
├── types/ # TypeScript type definitions
└── utils/ # Utility functions
.env.example # Environment variable template
tsconfig.json # TypeScript configuration
package.json # Node.js dependencies and scripts
Adding New Tools
Define a Zod schema for input validation
Create a ToolSchema definition
Implement the async handler function
Register the tool in the server
Add comprehensive error handling
Error Handling
All tools return structured responses:
// Success response
{
content: [{ type: "text", text: JSON.stringify(result) }]
}
// Error response
{
content: [{ type: "text", text: JSON.stringify(error) }],
isError: true
}
Security Considerations
Never commit service account keys to version control
Use environment variables for all sensitive configuration
Implement proper error handling to avoid information leakage
Regularly rotate service account keys
Follow Google Cloud security best practices
Contributing
Fork the repository
Create a feature branch
Make your changes with proper tests
Submit a pull request
License
MIT License - see LICENSE file for details
Support
For issues and questions:
Check the Google Calendar API documentation
Review MCP specification
Open an issue in this repository
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Provides comprehensive Google Calendar integration capabilities allowing AI assistants to list, create, update, and delete calendar events through a standardized Model Context Protocol.
Related MCP Servers
- -securityAlicense-qualityIntegrates Google Calendar with AI assistants through the Model Context Protocol, allowing users to view and manage calendar events through natural language interaction.Last updated -2712MIT License
- -securityAlicense-qualityEnables AI assistants to manage Google Calendar through natural language interactions with features like creating, updating, and deleting events, searching calendars, and supporting natural language date/time inputs.Last updated -22MIT License
- -securityFlicense-qualityEnables programmatic management of Google Calendar events through natural language interactions, supporting creation, reading, updating, and deletion of events with features for recurring events, attendees, and reminders.Last updated -2