Google Calendar MCP (nspady)
Manage Google Calendar events across multiple accounts with natural-language scheduling.
Add to your client
Copy the config for your MCP client and paste it into its config file.
npx -y @cocal/google-calendar-mcpPaste into ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"google-calendar-mcp-nspady": {
"command": "npx",
"args": [
"-y",
"@cocal/google-calendar-mcp"
],
"env": {
"GOOGLE_OAUTH_CREDENTIALS": "/absolute/path/to/gcp-oauth.keys.json"
}
}
}
}Step-by-step guides: Add to Claude Desktop · Add to Cursor · Add to Windsurf
Before you start
- Node.js LTS (run via npx, no global install needed) — or Docker for HTTP mode
- A Google Cloud project with the Google Calendar API enabled
- OAuth 2.0 credentials of type "Desktop app", downloaded as a JSON key file
- The path to that JSON file set via the GOOGLE_OAUTH_CREDENTIALS environment variable
- Your Google account(s) added as Test users on the OAuth consent screen (while the app is in Testing mode)
About Google Calendar MCP (nspady)
Google Calendar MCP (by nspady, published as @cocal/google-calendar-mcp) is a stdio MCP server that lets AI assistants read and manage Google Calendar: listing calendars, creating, updating, deleting, and searching events, checking free/busy availability, and responding to invitations — all through natural-language requests.
It supports multiple Google accounts simultaneously: the manage-accounts tool adds, lists, and removes accounts, and queries can span all configured accounts, enabling cross-calendar conflict detection. It also handles recurring-event modifications and can import events from images, PDFs, or web links.
Authentication is OAuth 2.0 using your own Google Cloud OAuth desktop credentials; tokens are stored locally in the system config directory and never sent anywhere except Google. The server runs over stdio by default and also offers an HTTP mode for Docker deployments. You can trim the exposed toolset with the ENABLED_TOOLS environment variable to reduce context usage.
Tools & capabilities (12)
list-calendarsList all calendars across configured accounts
list-eventsList events from a calendar within a time range
get-eventRetrieve a single event by ID
search-eventsSearch events by text query
create-eventCreate a new calendar event
update-eventUpdate an existing event, including recurring series
delete-eventDelete an event
respond-to-eventAccept, decline, or tentatively respond to an invitation
get-freebusyCheck free/busy availability across calendars
get-current-timeGet the current time/timezone for relative scheduling
list-colorsList available event colors
manage-accountsAdd, list, or remove connected Google accounts
When to use it
- Use it when you want to schedule, reschedule, or cancel meetings from a chat in natural language
- Use it when you need to find a free slot across several calendars or accounts before booking
- Use it when you manage personal and work Google accounts together and want a unified view
- Use it when you want to extract events from a screenshot, PDF, or link and add them to your calendar
- Use it when you need to bulk-search or audit upcoming events programmatically
- Use it when you want an agent to RSVP to invitations on your behalf
Quick setup
- 1In Google Cloud Console, create a project and enable the Google Calendar API
- 2Configure the OAuth consent screen (External) and add your Google account as a Test user
- 3Create OAuth 2.0 credentials of type "Desktop app" and download the JSON key file
- 4Add the server to your MCP client config with command `npx`, args `@cocal/google-calendar-mcp`, and GOOGLE_OAUTH_CREDENTIALS pointing to the JSON file
- 5Restart the client, then ask the assistant to authenticate — a browser window opens for the Google OAuth consent flow
- 6Verify with list-calendars or list-events
Security notes
You must create a Google Cloud OAuth client and point GOOGLE_OAUTH_CREDENTIALS at the credentials JSON; protect that file as it can authorize calendar access. In test mode OAuth tokens expire after 7 days, requiring periodic re-auth.
Google Calendar MCP (nspady) FAQ
Why do my credentials stop working after about a week?
When the OAuth app is in Testing mode, Google issues refresh tokens that expire after 7 days. Re-authenticate (clients like Claude Desktop reopen the browser automatically), or publish the app to Production to get longer-lived tokens.
What kind of OAuth credentials do I need?
OAuth 2.0 credentials of type "Desktop app" from your own Google Cloud project. Download the JSON and point GOOGLE_OAUTH_CREDENTIALS at it.
Can I connect more than one Google account?
Yes. Use the manage-accounts tool to add, list, and remove accounts, and the server can query and detect conflicts across all of them.
Where are my tokens stored — is anything sent to a third party?
Tokens are stored locally in your system config directory and are only ever sent to Google. Nothing is transmitted to any external server.
Can I reduce how many tools it exposes?
Yes. Set the ENABLED_TOOLS environment variable to a subset of tool names to cut down on context usage in your client.
Alternatives to Google Calendar MCP (nspady)
Compare all alternatives →
Self-hosted MCP server for Jira and Confluence Cloud and Server/Data Center.
Official Notion server to read, search, create, and update pages and databases in your workspace.
Read, search, and edit your Obsidian vault through the Local REST API community plugin.
Compare Google Calendar MCP (nspady) with: