A morning day-ahead briefing
Prompt
Every weekday at 7:30, list everything on my calendar for today with times and locations, flag any meeting with no agenda in its description, and save the result as today.md in my Notes folder.
Verified MCP server: Google Calendar
The Google Calendar MCP server, its live tool list captured on a real Mac.
- Tools enumerated2026-08-03macOS 14.4.1
- Package@cocal/google-calendar-mcp 2.6.2
- Self-reportedgoogle-calendar 2.6.2
- MCP protocol2025-06-18
- Runtimev25.8.1
The tool list below is a live capture from the running server; an authenticated tool call is still pending credentials.
The short answer
Last verified 2026-08-03
The Google Calendar MCP server lets an AI assistant read your calendar, search it, create and update events, reply to invitations, and check when you are free. Google publishes no MCP server of its own, so the one nearly every guide means is @cocal/google-calendar-mcp, an independent community project by Nate Spady: MIT licensed, 8,606 downloads in the last week, 1,164 stars, last released on 2026-06-01. We ran it instead of trusting its README. It started, spoke the protocol, and enumerated all 13 tools it exposes, and every name, description and parameter below is that capture word for word. It stopped exactly where the credentials stopped, at the first call that had to reach Google, and that error is printed here too. One warning before you go searching: the larger google_workspace_mcp project outranks it on GitHub stars and is a different thing, a twelve-service Python suite in which Calendar is one surface among many. [1][2][3][7]
Verification
How this MCP server was verified.
Method
We spawned the server with npx over stdio, completed the MCP initialize handshake, and called tools/list. The tool table below is that response, word for word, and the protocol version above is read straight off the raw initialize reply. With no credentials file the process exits before it speaks MCP at all, so we pointed GOOGLE_OAUTH_CREDENTIALS at an obviously fake gcp-oauth.keys.json instead of a real Google Cloud client: enough to boot the server and enumerate what it offers, not enough to reach Google. The one tool call we made came back with the server's own token error, printed below. An authenticated call is pending credentials.
Startup banner
No token file found at: /tmp/mcp-verify-home/.config/google-calendar-mcp/tokens.json ⚠️ No authenticated accounts found. Use the 'manage-accounts' tool with action 'add' to authenticate a Google account, or run: npx @cocal/google-calendar-mcp auth
One real tool call
tools/call list-calendars {}MCP error -32600: Authentication tokens are no longer valid. Please restart the server to re-authenticate.
Real lines from the captured result: enough to prove the call answered.
Tools
Every tool, enumerated from the running server.
The server answered tools/list with 13 tools on 2026-08-03. The names, descriptions and parameters below are its own words, copied from that response and never edited.
| Tool | What it does |
|---|---|
| list-calendarsaccount | List all available calendars |
| list-eventsaccountcalendarId*timeMintimeMaxtimeZonefieldsprivateExtendedPropertysharedExtendedProperty | List events from one or more calendars. Supports both calendar IDs and calendar names. |
| search-eventsaccountcalendarId*query*timeMin*timeMax*timeZonefieldsprivateExtendedPropertysharedExtendedProperty | Search for events in a calendar by text query. |
| get-eventaccountcalendarId*eventId*fields | Get details of a specific event by ID. |
| list-colorsaccount | List available color IDs and their meanings for calendar events |
| create-eventaccountcalendarId*eventIdsummary*descriptionstart*end*timeZonelocationattendeescolorIdremindersrecurrencetransparencyvisibilityguestsCanInviteOthersguestsCanModifyguestsCanSeeOtherGuestsanyoneCanAddSelfsendUpdatesconferenceDataextendedPropertiesattachmentssourcecalendarsToCheckduplicateSimilarityThresholdallowDuplicateseventTypefocusTimePropertiesoutOfOfficePropertiesworkingLocationProperties | Create a new calendar event. |
| create-eventsaccountcalendarIdtimeZonesendUpdatesevents* | Create multiple calendar events in bulk. Accepts shared defaults (account, calendarId, timeZone) that apply to all events, with per-event overrides. Skips conflict and duplicate detection for speed. |
| update-eventaccountcalendarId*eventId*summarydescriptionstartendtimeZonelocationattendeescolorIdremindersrecurrencesendUpdatesmodificationScopeoriginalStartTimefutureStartDatecheckConflictscalendarsToCheckconferenceDatatransparencyvisibilityguestsCanInviteOthersguestsCanModifyguestsCanSeeOtherGuestsanyoneCanAddSelfextendedPropertiesattachments | Update an existing calendar event with recurring event modification scope support. |
| delete-eventaccountcalendarId*eventId*sendUpdates | Delete a calendar event. |
| get-freebusyaccountcalendars*timeMin*timeMax*timeZonegroupExpansionMaxcalendarExpansionMax | Query free/busy information for calendars. Note: Time range is limited to a maximum of 3 months between timeMin and timeMax. |
| get-current-timeaccounttimeZone | Get the current date and time. Call this FIRST before creating, updating, or searching for events to ensure you have accurate date context for scheduling. |
| respond-to-eventcalendarId*eventId*accountresponse*commentmodificationScopeoriginalStartTimesendUpdates | Respond to a calendar event invitation with Accept, Decline, Maybe (Tentative), or No Response. |
| manage-accountsaction*account_id | Manage Google account authentication. Actions: 'list' (show accounts), 'add' (authenticate new account), 'remove' (remove account). |
Parameters marked with * are required.
Setup
Working configs, one per app.
Copy the block for the app you use. Each one is the configuration this server was verified with.
Claude Desktop
Open the file ~/Library/Application Support/Claude/claude_desktop_config.json (in Claude Desktop: Settings, then Developer, then Edit Config) and add:
{
"mcpServers": {
"google-calendar": {
"command": "npx",
"args": [
"-y",
"@cocal/google-calendar-mcp"
],
"env": {
"GOOGLE_OAUTH_CREDENTIALS": "/Users/yourname/Documents/gcp-oauth.keys.json"
}
}
}
}GOOGLE_OAUTH_CREDENTIALS is the full path to the OAuth client file you download from the Google Cloud Console, and it is the one field you have to get right: the server exits at startup if that file is not there. Save the file somewhere it will not move, then quit and reopen Claude Desktop. [9][4][5]
Claude Code
One command in your terminal:
claude mcp add --env GOOGLE_OAUTH_CREDENTIALS=/Users/yourname/Documents/gcp-oauth.keys.json --transport stdio google-calendar -- npx -y @cocal/google-calendar-mcp
Everything after the double dash is the exact command Claude Code will run. Use an absolute path for the credentials file, not a path starting with a tilde. The --transport flag sits between the --env pair and the server name on purpose: the docs warn that a name placed straight after --env is read as another KEY=value pair and rejected. [10]
Cursor
Add to ~/.cursor/mcp.json for every project, or to .cursor/mcp.json inside one project:
{
"mcpServers": {
"google-calendar": {
"command": "npx",
"args": [
"-y",
"@cocal/google-calendar-mcp"
],
"env": {
"GOOGLE_OAUTH_CREDENTIALS": "/Users/yourname/Documents/gcp-oauth.keys.json"
}
}
}
}Cursor picks the file up on restart. The env block holds a path, not a secret, but the file it points at is your OAuth client: keep both out of any repository you push. [11]
Routines
No JSON file and no terminal. In Routines: Settings, then Assistant, then Connections, then Add MCP Server. Switch the form to Command (stdio) and enter:
Name Google Calendar Command npx Arguments -y @cocal/google-calendar-mcp Environment Variables GOOGLE_OAUTH_CREDENTIALS /Users/yourname/Documents/gcp-oauth.keys.json
The Arguments field splits on spaces, so keep it to exactly those three words. The path to your OAuth client file goes in Environment Variables, never in Arguments, and it has to be a full path starting with /Users. Click Test Connection first: a working server answers with its tool count, thirteen for this one. [12][5]
No terminal needed
Set the Google Calendar MCP server up without the terminal.
If you have never opened Terminal and never want to, this is your path. Routines is a Mac app that runs MCP servers for you: fill in a few fields once, and this server's tools are available to your AI in chat and in scheduled routines. Worth knowing before you start: Routines also ships a one-click Google Calendar connector that needs none of this, so this walkthrough is for people who want this particular server, with its thirteen tools, rather than calendar access in general. The fiddly part either way is the Google side, and it is a ten-minute detour on Google's own site.
01
Install Routines
Download the app from getroutines.ai/download, drag it to Applications, and sign in.
02
Make an OAuth client in the Google Cloud Console
Go to console.cloud.google.com, create a project or pick one you already have, and enable the Google Calendar API for it. Then open the OAuth consent screen, choose External, and add your own Google address under Test users, or the sign-in will be refused later. Finally open Credentials, click Create Credentials, choose OAuth client ID, and pick Desktop app as the type.
03
Download the key file and park it somewhere stable
Google offers the new client as a JSON download. Rename it gcp-oauth.keys.json and save it somewhere it will not move, for example in your Documents folder. This file identifies your own little app to Google; it is not your calendar and not a password, but treat it like a private file anyway.
04
Add the server in Routines
Click your account at the bottom of the sidebar and choose Settings. Open the Assistant section, then the Connections tab, scroll to MCP Servers, and click Add MCP Server. Switch the form to Command (stdio): this server is a command, not a web address. Name: Google Calendar. Command: npx. Arguments: -y @cocal/google-calendar-mcp, exactly those three words.
05
Point it at the key file, then test
In Environment Variables add GOOGLE_OAUTH_CREDENTIALS with the full path of the file you saved, such as /Users/yourname/Documents/gcp-oauth.keys.json. Click Test Connection: Routines starts the server without saving it and reports how many tools it found, thirteen for this one. Then click Add Server.
06
Sign in to Google once, then use it
The server starts without a Google session and says so. In chat, ask your assistant to use the manage-accounts tool with the action add. It opens a Google sign-in page in your browser, you approve the calendar permissions, and the resulting token is stored on your Mac. After that the tools work in chat right away. To let a scheduled routine use them, open the routine, find the Tools & connections card, and tick the server under Apps.
Routine ideas
Routines worth scheduling.
Once the server is connected, a scheduled routine can use its tools while you are away. Copy a prompt, paste it into Routines, and pick a time.
A Sunday week-ahead review
Prompt
Every Sunday at 18:00, look at the coming seven days on my calendar, tell me which days are back to back with no gap longer than 30 minutes, list the meetings I have not accepted yet, and write it all to week-ahead.md.
A focus-time finder
Prompt
Every Monday at 8:00, check my free time for the next five working days between 9:00 and 17:00, find the three longest uninterrupted blocks, and create a two-hour Deep work event in the best one.
Troubleshooting
The errors we hit, and what fixed them.
Real errors captured during the verification run, printed exactly as the server returned them.
The server exits the second it starts
What you see
Failed to start server: Error loading OAuth keys: OAuth credentials not found. Please provide credentials using one of these methods: 1. Environment variable: Set GOOGLE_OAUTH_CREDENTIALS to the path of your credentials file: export GOOGLE_OAUTH_CREDENTIALS="/path/to/gcp-oauth.keys.json" 2. Default file path: Place your gcp-oauth.keys.json file in the package root directory. Token storage: - Tokens are saved to: /tmp/mcp-verify-home/.config/google-calendar-mcp/tokens.json - To use a custom token location, set GOOGLE_CALENDAR_MCP_TOKEN_PATH environment variable To get OAuth credentials: 1. Go to the Google Cloud Console (https://console.cloud.google.com/) 2. Create or select a project 3. Enable the Google Calendar API 4. Create OAuth 2.0 credentials 5. Download the credentials file as gcp-oauth.keys.json Original error: ENOENT: no such file or directory, open '/tmp/mcp-verify-home/Documents/gcp-oauth.keys.json'
The fix
The credentials file is the very first thing the server loads, before it will speak MCP at all, so a missing or misspelled path kills it at startup and your client just reports that the server failed. We triggered this twice on purpose, once with the variable unset and once pointing at a file that was not there; the last line of the message names the exact path it tried. Set GOOGLE_OAUTH_CREDENTIALS to the full path of your downloaded file, with no tilde and no quotes around it in Routines, and start it again.
The tools are listed, but every call says the tokens are not valid
What you see
MCP error -32600: Authentication tokens are no longer valid. Please restart the server to re-authenticate.
The fix
This is what our own run produced, because we booted the server with a placeholder credentials file on purpose: it can describe its tools without Google, but the first real call needs a signed-in account. Run the manage-accounts tool with the action add, or the auth command in the server's own startup message, and approve the calendar permissions in the browser window it opens. If it used to work and stopped after about a week, see the FAQ below: an OAuth consent screen still in Testing mode expires its tokens every seven days.
A tool call is rejected before it ever reaches Google
What you see
MCP error -32602: Input validation error: Invalid arguments for tool list-events: Invalid input at calendarId
The fix
The server validates arguments against its own schema first, and calendarId is required on most of the event tools. We produced this by calling list-events with no arguments at all. In practice an assistant hits it when it guesses at a calendar: tell it to call list-calendars first and use an id from that list, or the word primary for your main calendar.
You limited the tool list and the server refuses to start
What you see
Error: Invalid tool name(s): not-a-real-tool-name. Available tools: list-calendars, list-events, search-events, get-event, list-colors, create-event, create-events, update-event, delete-event, get-freebusy, get-current-time, respond-to-event, manage-accounts
The fix
The optional --enable-tools flag whitelists tools by name, and an unknown name is fatal rather than ignored. Useful side effect: the error prints the server's full list of names, which is a second independent confirmation of the thirteen in the table above. Copy the names exactly, hyphens and all.
Your MCP client cannot start the server at all
The fix
The npx command belongs to Node.js. If Node is not installed on your Mac, every client on this page fails at the spawn step before the server can say anything. Install Node from nodejs.org, restart your MCP client, and try again.
FAQ
Questions people ask.
What is the Google Calendar MCP server?
It is a small program that sits between an AI assistant and your Google Calendar and speaks the Model Context Protocol. Once connected, an assistant such as Claude can list your calendars, read and search events, create and update them, delete them, reply to invitations, and query when you are free. It runs as a local process on your Mac and talks to your AI app over stdio; the same package can also be self-hosted over HTTP if you want it on a server instead. [4]
Which Google Calendar MCP server should I use?
Google publishes none, so every option is a community project. @cocal/google-calendar-mcp, the one on this page, is the calendar-specific leader by a wide margin: 8,606 downloads last week against 614 for the next calendar-only package, and 1,164 stars. Its name is also crowded, with an unscoped google-calendar-mcp by a different author and several direct forks, so copy the scoped name exactly. The one genuine alternative is google_workspace_mcp, published on PyPI as workspace-mcp: more stars, but a twelve-service Python suite covering Gmail, Drive, Docs and more, where Calendar is one surface among many. Pick that one if you want all of Google Workspace, and this one if you want a calendar. [2][6][3][7][8]
What tools does the Google Calendar MCP server include?
The running server exposes 13 tools: reading (list-calendars, list-events, search-events, get-event, list-colors, get-freebusy, get-current-time), writing (create-event, create-events, update-event, delete-event, respond-to-event), and one for signing in (manage-accounts). The table above is the live tools/list output, word for word, and the server printed the same thirteen names again in an unrelated error during our run.
Does it need an API key or a Google account?
A Google account, yes, and one piece of setup that is easy to underestimate: you create your own OAuth client in the Google Cloud Console, download it as gcp-oauth.keys.json, and point the server at that file. There is no API key to paste and nothing to pay for. One gotcha to plan for: while your OAuth consent screen is still in Testing mode, Google expires the resulting tokens every seven days, so the connection stops working after about a week until you sign in again or publish the consent screen. [5]
Is the Google Calendar MCP server safe?
It is an independent community project, MIT licensed and open to read, with no corporate owner behind it: worth knowing before it holds a token to your calendar. The real question is scope. Five of its thirteen tools write, and delete-event and update-event act immediately, so a misread instruction can move or remove a real meeting. Give it a calendar rather than your whole account where you can, keep the OAuth client file to yourself, and if you only want reading, the --enable-tools flag lets you start it with the read-only tools alone. [3][4]
Do I need the terminal to set it up?
No. In Routines you fill in the fields in Settings and click Test Connection, and you sign in to Google from a chat message rather than a command; the walkthrough above shows every click. Claude Desktop needs a small JSON file edited once. Only Claude Code is terminal-first by nature. If you want calendar access and not this specific server, Routines also has a one-click Google Calendar connector that skips the Google Cloud Console entirely. [12][9]
Which apps can use the Google Calendar MCP server?
Any MCP client that can launch a local stdio server: Claude Desktop, Claude Code, Cursor and Routines all can, and the exact config for each is above. The server itself is the same in every client; only the place you paste the config differs, and every one of them needs the same GOOGLE_OAUTH_CREDENTIALS path. [9][10][11][12]
Sources
Every external claim, receipted.
Anything on this page we did not observe in the run is linked here, with the date we read it. The run itself is the receipt for the rest.
[1]
npm registry: @cocal/google-calendar-mcpaccessed 2026-08-03Latest version 2.6.2, published 2026-06-01, MIT, repository nspady/google-calendar-mcp.
[2]
npm downloads API: last weekaccessed 2026-08-038,606 downloads for the week ending 2026-08-01. The next calendar-specific package, @gongrzhe/server-calendar-autoauth-mcp, had 614.
[3]
GitHub: nspady/google-calendar-mcpaccessed 2026-08-031,164 stars, MIT, not archived, last push 2026-06-01, per the GitHub API.
[4]
nspady/google-calendar-mcp READMEaccessed 2026-08-03Install and config for Claude Desktop, the tool table, the environment variables, the optional HTTP transport and the maintainer note.
[5]
google-calendar-mcp docs: authenticationaccessed 2026-08-03OAuth client setup, the gcp-oauth.keys.json shape, token storage paths, and the seven-day token expiry while the consent screen is in Testing mode.
[6]
npm registry search: google-calendar-mcpaccessed 2026-08-03The crowded namespace: an unscoped google-calendar-mcp by a different author, plus forks under @automate-army, @dongtran and @enterpret.
[7]
GitHub: taylorwilsdon/google_workspace_mcpaccessed 2026-08-032,958 stars, MIT, not archived, last push 2026-08-02. Twelve Google Workspace services and 120 or more tools, in Python.
[8]
PyPI: workspace-mcpaccessed 2026-08-03Version 1.23.1. The Python and uvx run model, in contrast with npx here.
[9]
modelcontextprotocol.io: Connect to local MCP serversaccessed 2026-08-03The official Claude Desktop quickstart and the config file location.
[10]
Claude Code docs: MCPaccessed 2026-08-03The claude mcp add syntax for local stdio servers, the --env flag, and the warning about placing the server name straight after --env.
[11]
Cursor docs: Model Context Protocolaccessed 2026-08-03The mcp.json shape, including the env block, and the file locations.
[12]
Routines: Connectorsaccessed 2026-08-03How Routines runs one-click OAuth connectors, Google Calendar among them, and any MCP server.
This page describes Google Calendar as it behaved in one dated run on one Mac. Versions move: if something here no longer matches what you see, the capture date at the top says how old the reading is.
Behind this directory
Routines, the app behind this directory, runs MCP servers like this one without a terminal: see how connectors work. The briefings it writes stay markdown files on your Mac, and there is no cloud bill. Download Routines