Home / MCP / Google Calendar MCP Server
Provides multi-account Google Calendar access with event management, scheduling, and smart import across calendars.
Configuration
View docs{
"mcpServers": {
"google_calendar": {
"command": "npx",
"args": [
"@cocal/google-calendar-mcp"
],
"env": {
"GOOGLE_OAUTH_CREDENTIALS": "/path/to/your/gcp-oauth.keys.json",
"GOOGLE_CALENDAR_MCP_TOKEN_PATH": "/path/to/tokens"
}
}
}
}This MCP server provides Google Calendar integration for AI assistants, enabling multi-account and multi-calendar access, smart scheduling, event management, free/busy checks, and advanced import from images or links. It helps you coordinate complex schedules across multiple Google accounts while keeping control on your local environment.
You connect your Google Calendar MCP server to your client (such as Claude Desktop) to manage calendars across multiple accounts. Use the multi-account features to query, create, update, and delete events across your personal, work, and other calendars. Take advantage of free/busy checks, smart date parsing, and cross-calendar conflict detection to schedule efficiently. Start by authenticating the server, then use the available tools to list calendars, view upcoming events, search for events, and perform typical calendar operations across all connected accounts.
Prerequisites: Node.js (LTS) and a Google Cloud project with the Calendar API enabled. Have OAuth 2.0 Desktop app credentials ready and a credentials file path you can reference.
Option 1: Use with npx (Recommended) Install via npx and configure the environment variable that points to your credentials file.
{
"mcpServers": {
"google-calendar": {
"command": "npx",
"args": ["@cocal/google-calendar-mcp"],
"env": {
"GOOGLE_OAUTH_CREDENTIALS": "/path/to/your/gcp-oauth.keys.json"
}
}
}
}Option 2: Local Installation Clone the project, install dependencies, and build. Then configure your client to point to the local runtime.
git clone https://github.com/nspady/google-calendar-mcp.git
cd google-calendar-mcp
npm install
npm run build
```
Then add to your Claude Desktop config using the local path or by specifying the path with the `GOOGLE_OAUTH_CREDENTIALS` environment variable.Option 3: Docker Installation Copy credentials, then run with Docker Compose.
git clone https://github.com/nspady/google-calendar-mcp.git
cd google-calendar-mcp
cp /path/to/your/gcp-oauth.keys.json .
docker compose upFirst run体: Start the client (Claude Desktop) and complete the OAuth flow when prompted. After authentication, calendar features are available.
Re-authentication: If tokens expire, re-authenticate via the same flow. You can also run re-auth commands for npx or local installs to refresh tokens.
Managing multiple accounts: You can connect and manage several Google accounts. Use the account management UI at the provided endpoint or corresponding CLI commands to add, list, and switch between accounts.
Environment variables you may configure include the path to your Google OAuth credentials and an optional custom token storage location.
Claude Desktop configuration locations vary by OS. For macOS the config file is at ~/Library/Application Support/Claude/claude_desktop_config.json. For Windows it is at %APPDATA%\Claude\claude_desktop_config.json.
OAuth tokens are stored securely in your system’s config directory and never leave your machine. All calendar operations require explicit user consent.
If you encounter issues, ensure you are using a Desktop App OAuth credential, check that the test user is added for your Google Cloud project, and verify file paths are absolute and accessible.
Common troubleshooting steps include re-running installation steps, checking Node.js version, and ensuring no other process blocks required ports.
Cross-calendar availability: Ask for availability across personal and work calendars for a meeting in a specific locale and duration.
Import events from images or PDFs: Use supported images to extract event details and add them to your calendar.
Calendar analysis and attendee management: Analyze upcoming events, check attendee responses, and respond to invitations as needed.
List all available calendars for all connected accounts.
List events with date filtering across connected calendars.
Search events by text query across calendars.
Create new calendar events in one or more calendars.
Update existing calendar events.
Delete events from calendars.
Respond to event invitations (Accept, Decline, Maybe, No Response).
Check availability across calendars, including external calendars.
List available event colors.