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 and https://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).
⚠️ 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
git clone https://github.com/nspady/google-calendar-mcp.git
cd google-calendar-mcp
npm install
npm run build
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
git clone https://github.com/nspady/google-calendar-mcp.git
cd google-calendar-mcp
cp /path/to/your/gcp-oauth.keys.json .
docker compose up
See the Docker deployment guide for detailed configuration options including HTTP transport mode.
First Run
Start Claude Desktop
Ask Claude to authenticate with the Google Calendar MCP server (e.g., "Authenticate with Google Calendar"). This step is required before using any calendar tool — without it, requests will fail with a -32600 error.
Complete the OAuth flow in your browser
You're ready to use calendar features!
Using Claude Code? The same steps apply — just ask Claude to authenticate with the Google Calendar MCP server from your CLI session before using any calendar tool.
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:
A service account carries its own long-lived key, so there is no browser consent step
and no refresh token to expire. This is the alternative to publishing your OAuth app
when the weekly re-authentication above is impractical — headless servers, containers,
CI, or an app you would rather leave in Testing status.
Which calendars this works for
Calendar
Works?
How access is granted
Personal @gmail.com calendar
Yes
Share the calendar with the service account's e-mail address
Google Workspace calendar
Yes
Share it, or use domain-wide delegation to impersonate a user
Any calendar shared with you by someone else
No
The owner must share it with the service account directly
Sharing is what grants access — the service account is a separate identity and sees
nothing by default. Domain-wide delegation is not required for the personal-calendar
case; it is only needed if you want the service account to act as a user.
Limitations
Attendees cannot be invited. The API rejects this with "Service accounts cannot
invite attendees without Domain-Wide Delegation of Authority". Everything else —
creating, updating, deleting, searching, free/busy — works normally.
calendarId must be explicit.primary refers to the service account's own,
empty calendar; pass the calendar's address (e.g. [email protected]) instead.
list-calendars returns nothing. A calendar shared with a service account does not
appear in its calendarList unless explicitly added. Address calendars by id.
Setup
Create a service account and a JSON key in your Google Cloud project:
gcloud iam service-accounts create calendar-mcp --project=YOUR_PROJECT
gcloud iam service-accounts keys create service-account.json \
--iam-account=calendar-mcp@YOUR_PROJECT.iam.gserviceaccount.com
In Google Calendar, open Settings → your calendar → Share with specific people,
add the service account's e-mail and grant "Make changes to events".
The key is detected by its contents ("type": "service_account"), not by a mode flag,
so switching an existing install over is a one-file change. Three things are consulted,
and the first one that yields an answer wins:
GOOGLE_SERVICE_ACCOUNT_KEY — an explicit demand for service account mode. If
that file is missing, unreadable, or not a service account key, the server fails
to start and says so, rather than falling back to OAuth and leaving you to guess
why.
This server's own credentials file — GOOGLE_OAUTH_CREDENTIALS if you set it,
otherwise gcp-oauth.keys.json. It is read by content, so putting a service account
key at that path works. If it holds ordinary OAuth client credentials, that settles
it: you have an OAuth setup, and step 3 is skipped.
GOOGLE_APPLICATION_CREDENTIALS — the shared Google variable, often already set
for unrelated tooling. It is consulted only when this server has no credentials file
of its own (GOOGLE_OAUTH_CREDENTIALS unset and no usable gcp-oauth.keys.json), so
it never overrides a working OAuth install. If you rely on the default
gcp-oauth.keys.json and that file goes missing, this variable is used instead; set
GOOGLE_OAUTH_CREDENTIALS explicitly to rule that out, since an explicit path that
can't be read fails startup rather than falling back. A problem with it is warned
about, never fatal.
The server logs which credentials it chose, and where they came from, on every startup.
Set GOOGLE_SERVICE_ACCOUNT_SUBJECT only if you are using domain-wide delegation.
Treat the key file as a credential: it does not expire. chmod 600 it, keep it out of
version control, and delete the key in the Cloud Console if it is ever exposed.
Managing Multiple Accounts
Connect multiple Google accounts and use them simultaneously.
In chat (recommended): Use the manage-accounts tool to add, list, or remove accounts directly from your AI assistant - no terminal needed. See the Authentication Guide for details.
CLI: For initial setup, use npm run account auth <nickname> (e.g., npm run account auth work).
HTTP / Docker: Visit http://localhost:3000/accounts to manage accounts in the browser.
When no account parameter is supplied to a tool, read-only tools merge results from all accounts, while write tools auto-select the account with appropriate permissions.
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:
Please provide availability looking at both my personal and work calendar for this upcoming week.
I am looking for a good time to meet with someone in London for 1 hr.
Add events from screenshots, images and other data sources:
Add this event to my calendar based on the attached screenshot.
Supported image formats: PNG, JPEG, GIF
Images can contain event details like date, time, location, and description
Calendar analysis:
What events do I have coming up this week that aren't part of my usual routine?
Check attendance:
Which events tomorrow have attendees who have not accepted the invitation?
Respond to invitations:
Accept the team meeting invitation on my calendar for tomorrow at 2pm
Decline with a note:
Decline the Friday meeting with a note that I have a scheduling conflict
Respond to recurring events:
Accept just this week's standup, but keep future instances as tentative
Decline all future Monday planning meetings
Auto coordinate events:
Here's some availability that was provided to me by someone. {available times}
Take a look at the times provided and let me know which ones are open on my calendar.
Available Tools
Tool
Description
list-calendars
List all available calendars
list-events
List events with date filtering
get-event
Get details of a specific event by ID
search-events
Search events by text query
create-event
Create new calendar events, optionally colored with an event label (eventLabelId)
create-events
Create multiple events in one call with shared defaults (skips conflict detection)
update-event
Update existing events, including setting or removing an event label
delete-event
Delete events
respond-to-event
Respond to event invitations (Accept, Decline, Maybe, No Response)
get-freebusy
Check availability across calendars, including external calendars
get-current-time
Get current date and time in calendar's timezone
list-colors
List legacy event colors, plus a calendar's event labels (custom colors) when given calendarId
If Google Calendar MCP has been useful to you and you're so inclined, I'd greatly appreciate it if you'd consider sponsoring my open source work.
Thanks! – Nate
Configuration
Environment Variables:
CLI flags take precedence over environment variables. Malformed values (for example a non-numeric PORT or an unknown TRANSPORT) stop the server at startup with an error, and the resolved configuration is logged to stderr on start.
Variable
CLI flag
Default
Description
GOOGLE_OAUTH_CREDENTIALS
gcp-oauth.keys.json in the package root
Path to the OAuth credentials file
GOOGLE_OAUTH_REDIRECT_BASE
unset (loopback http://localhost:<port>)
Public base URL for the OAuth callback when authenticating through a tunnel or reverse proxy (see docs/authentication.md)
GOOGLE_SERVICE_ACCOUNT_KEY
unset
Path to an explicit service account key file
GOOGLE_APPLICATION_CREDENTIALS
unset
Ambient Google credentials file, used when this server has no OAuth credentials file
GOOGLE_SERVICE_ACCOUNT_SUBJECT
unset
Workspace user to impersonate with domain-wide delegation
GOOGLE_CALENDAR_MCP_TOKEN_PATH
$XDG_CONFIG_HOME/google-calendar-mcp/tokens.json
Custom token storage location
XDG_CONFIG_HOME
~/.config
Base config directory for token storage (ignored if GOOGLE_CALENDAR_MCP_TOKEN_PATH is set)
GOOGLE_ACCOUNT_MODE
normal
Account nickname used for single-account operations and the auth command
ENABLED_TOOLS
--enable-tools
all tools
Comma-separated list of tools to expose (see Tool Filtering)
TRANSPORT
--transport
stdio
Transport type: stdio or http
PORT
--port
3000
HTTP transport port (1-65535)
HOST
--host
127.0.0.1
HTTP transport bind address
DEBUG
--debug
false
Reserved: true is accepted and shown in the startup log but currently enables no extra logging
GOOGLE_CALENDAR_API_BASE_URL
https://www.googleapis.com
Send Calendar API calls to this base URL instead (see below)
NODE_ENV
unset
test skips startup authentication and uses the test account namespace (for the test suite)
GOOGLE_CALENDAR_API_BASE_URL is for an egress proxy that originates TLS itself, e.g. http://127.0.0.1:10255/tenant-a/calendar. A path prefix is kept, so requests go to <url>/calendar/v3/.... Calendar access tokens and request data are sent to this URL, unencrypted with http://, so point it only at a proxy you control. Token refresh and the login flow are unchanged: refresh still has to reach oauth2.googleapis.com directly or through HTTPS_PROXY, whatever this is set to. With HTTPS_PROXY set, list this URL's host in NO_PROXY to reach it directly; batch requests go to it directly either way.
Tool Filtering
You can limit which tools are exposed to the AI assistant using the --enable-tools flag or ENABLED_TOOLS environment variable. This is useful for:
Reducing context usage: Each tool consumes tokens from the AI's context window. Limiting tools can help preserve context for longer conversations.
Security: Restrict capabilities to read-only operations or specific functionality.
Simplicity: Only expose the tools your workflow actually needs.
Note: The manage-accounts tool is always available regardless of filtering, as it's needed for authentication management.
When tool filtering is active, the server provides instructions to the AI assistant listing which tools are disabled. This allows the AI to inform users that additional functionality exists but is currently unavailable, without consuming the full token cost of those tool schemas.
If the list is empty or contains only commas, the server will fail to start with an error.
If an invalid tool name is specified, the server will fail to start with an error listing all available tools.
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
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 3500-3505
Build Errors:
Run npm install && npm run build again
Check Node.js version (use LTS)
Delete the build/ directory and run npm run build
"Something went wrong" screen during browser authentication
अभी टूल सूची नहीं है। रिमोट सर्वर को पहले हेल्थ चेक के बाद सूची मिलती है।
FAQ
सवाल
@cocal/google Calendar कैसे इंस्टॉल करें?
इस पेज पर Cursor, Claude Desktop, Claude Code या VS Code के लिए stdio कॉन्फ़िग कॉपी करें। यह पब्लिशर का इंस्टॉल इस्तेमाल करता है, PlugMCP प्रॉक्सी नहीं।
क्या @cocal/google Calendar के लिए API key चाहिए?
इस रिकॉर्ड में कोई ज़रूरी एनवायरनमेंट वेरिएबल दर्ज नहीं है।
@cocal/google Calendar कौन सा ट्रांसपोर्ट इस्तेमाल करता है?
@cocal/google Calendar stdio पर लोकल चलता है।
@cocal/google Calendar की पिछली जाँच कब हुई थी?
पिछली जाँच 2026-11-17 को हुई। Google Calendar MCP Server with extensive support for calendar management