Allows LLMs to read, create, and manage calendar events through a standardized interface, including listing calendars, listing events, creating events, updating events, deleting events, and processing events from screenshots and images.
Google Calendar MCP Server
A Model Context Protocol (MCP) server that provides Google Calendar integration for AI assistants like Claude.
Features
- Multi-Calendar Support: List events from multiple calendars simultaneously
- Event Management: Create, update, delete, and search calendar events
- Recurring Events: Advanced modification capabilities for recurring events
- Free/Busy Queries: Check availability across calendars
- Smart Scheduling: Natural language understanding for dates and times
- Inteligent Import: Add calendar events from images, PDFs or web links
Quick Start
Prerequisites
- A Google Cloud project with the Calendar API enabled
- OAuth 2.0 credentials (Desktop app type)
Google Cloud Setup
- Go to the Google Cloud Console
- Create a new project or select an existing one.
- Enable the Google Calendar API for your project. Ensure that the right project is selected from the top bar before enabling the API.
- Create OAuth 2.0 credentials:
- Go to Credentials
- Click "Create Credentials" > "OAuth client ID"
- Choose "User data" for the type of data that the app will be accessing
- Add your app name and contact information
- Add the following scopes (optional):
https://www.googleapis.com/auth/calendar.events
andhttps://www.googleapis.com/auth/calendar
- Select "Desktop app" as the application type (Important!)
- Save the auth key, you'll need to add its path to the JSON in the next step
- Add your email address as a test user under the Audience screen
- Note: it might take a few minutes for the test user to be added. The OAuth consent will not allow you to proceed until the test user has propagated.
- Note about test mode: While an app is in test mode the auth tokens will expire after 1 week and need to be refreshed (see Re-authentication section below).
Installation
Option 1: Use with npx (Recommended)
Add to your Claude Desktop configuration:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
⚠️ Important Note for npx Users: When using npx, you must specify the credentials file path using the GOOGLE_OAUTH_CREDENTIALS
environment variable.
Option 2: Local Installation
Then add to Claude Desktop config using the local path or by specifying the path with the GOOGLE_OAUTH_CREDENTIALS
environment variable.
Option 3: Docker Installation
See the Docker deployment guide for detailed configuration options including HTTP transport mode.
First Run
- Start Claude Desktop
- The server will prompt for authentication on first use
- Complete the OAuth flow in your browser
- You're ready to use calendar features!
Re-authentication
If you're in test mode (default), tokens expire after 7 days. If you are using a client like Claude Desktop it should open up a browser window to automatically re-auth. However, if you see authentication errors you can also resolve by following these steps:
For npx users:
For local installation:
To avoid weekly re-authentication, publish your app to production mode (without verification):
- Go to Google Cloud Console → "APIs & Services" → "OAuth consent screen"
- Click "PUBLISH APP" and confirm
- Your tokens will no longer expire after 7 days but Google will show a more threatning warning when connecting to the app about it being unverified.
See Authentication Guide for details.
Example Usage
Along with the normal capabilities you would expect for a calendar integration you can also do really dynamic, multi-step processes like:
- Cross-calendar availability:
- Add events from screenshots, images and other data sources:Supported image formats: PNG, JPEG, GIF Images can contain event details like date, time, location, and description
- Calendar analysis:
- Check attendance:
- Auto coordinate events:
Available Tools
Tool | Description |
---|---|
list-calendars | List all available calendars |
list-events | List events with date filtering |
search-events | Search events by text query |
create-event | Create new calendar events |
update-event | Update existing events |
delete-event | Delete events |
get-freebusy | Check availability across calendars, including external calendars |
list-colors | List available event colors |
Documentation
- Authentication Setup - Detailed Google Cloud setup
- Advanced Usage - Multi-account, batch operations
- Deployment Guide - HTTP transport, remote access
- Docker Guide - Docker deployment with stdio and HTTP modes
- OAuth Verification - Moving from test to production mode
- Architecture - Technical architecture overview
- Development - Contributing and testing
- Testing - Unit and integration testing guide
Configuration
Environment Variables:
GOOGLE_OAUTH_CREDENTIALS
- Path to OAuth credentials fileGOOGLE_CALENDAR_MCP_TOKEN_PATH
- Custom token storage location (optional)
Claude Desktop Config Location:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%\Claude\claude_desktop_config.json
Security
- OAuth tokens are stored securely in your system's config directory
- Credentials never leave your local machine
- All calendar operations require explicit user consent
Troubleshooting
- OAuth Credentials File Not Found:
- For npx users: You must specify the credentials file path using
GOOGLE_OAUTH_CREDENTIALS
- Verify file paths are absolute and accessible
- For npx users: You must specify the credentials file path using
- Authentication Errors:
- Ensure your credentials file contains credentials for a Desktop App type
- Verify your user email is added as a Test User in the Google Cloud OAuth Consent screen
- Try deleting saved tokens and re-authenticating
- Check that no other process is blocking ports 3000-3004
- Build Errors:
- Run
npm install && npm run build
again - Check Node.js version (use LTS)
- Delete the
build/
directory and runnpm run build
- Run
- "Something went wrong" screen during browser authentication
- Perform manual authentication per the below steps
- Use a Chromium-based browser to open the authentication URL. Test app authentication may not be supported on some non-Chromium browsers.
Manual Authentication
For re-authentication or troubleshooting:
License
MIT
Support
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Create, search and manage all of your Google calendar events with the powers of MCP.
Related MCP Servers
- -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 -42TypeScriptMIT License
- -securityAlicense-qualityEnables interaction with Gmail and Google Calendar using the MCP protocol, supporting multiple Google accounts, email management, and calendar operations through natural language.Last updated -12TypeScriptMIT License
- -securityFlicense-qualityA Model Completion Prompt (MCP) plugin that allows users to create events in Google Calendar with customizable attributes like times, description, location, attendees, and timezone.Last updated -1Python
- -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 -2Python