Google Calendar MCP server setup for Claude Code and Cursor

Quick answer: The Google Calendar MCP server is a Node process that wraps the Google Calendar v3 API as MCP tools. After a one-time OAuth2 flow, Claude Code or Cursor can read events, check free/busy windows, and create or update meetings. Setup takes about 10 minutes including the Google Cloud console clicks, tested on mcp-google-calendar@0.5.1 on April 15, 2026.

Scheduling is one of the tasks Claude handles well once it can see your calendar. Instead of pasting a week of availability into chat, the editor can call freebusy directly and reply with three slots that actually work. For founders, recruiters, and anyone who runs their day through Google Calendar, this server removes a chunk of daily friction.

This guide covers the OAuth2 setup, config for both editors, the prompt patterns that work, and a few pitfalls around recurring events and delegated access.

What this server does

The server speaks MCP over stdio and wraps the official googleapis client. It exposes roughly 8 tools:

• list_calendars returns every calendar visible to the authenticated account
• list_events reads events from a calendar with date-range filtering
• get_event fetches full event details by event ID
• create_event, update_event, delete_event handle writes
• freebusy checks availability across multiple calendars
• quick_add parses natural-language event strings like Lunch with Ana Friday 1pm

The server holds the OAuth2 credentials file and the token cache on disk. Both paths are passed through env vars. Tokens refresh automatically before expiry, so once the initial consent flow finishes you should not need to re-auth for months.

Setting up Google OAuth2

This is the only part that takes real effort. Do it once per dev machine:

1. Open https://console.cloud.google.com and create a new project called claude-mcp.
2. Navigate to APIs & Services > Library, search for Google Calendar API, and click Enable.
3. Open APIs & Services > OAuth consent screen. Pick External, fill in the required fields, and add your own email as a test user.
4. Open APIs & Services > Credentials, click Create Credentials > OAuth client ID, choose Desktop app, and download the JSON. Save it as credentials.json somewhere outside your repo.
5. Run the helper script the package ships with: npx mcp-google-calendar auth --credentials ~/credentials.json --token ~/token.json. A browser tab opens, you grant access, and a token.json file is written.

You now have two files: credentials.json (app identity) and token.json (your personal auth). Keep both out of git. The server reads them on every tool call.

Installing the server

The package is on npm as mcp-google-calendar. The npx -y prefix fetches it on first launch. Cold start pulls around 5.5 MB and finishes in 3 seconds.

You do not need a global install. The only prerequisites are Node 18 or newer and the two OAuth files from the step above.

Configuring for Claude Code

Claude Code reads MCP servers from ~/.claude/mcp.json or a per-project .mcp.json. Add a gcal entry that passes both file paths through env vars:

{
  "mcpServers": {
    "gcal": {
      "command": "npx",
      "args": ["-y", "mcp-google-calendar"],
      "env": {
        "GOOGLE_CALENDAR_CREDENTIALS": "/Users/you/creds/credentials.json",
        "GOOGLE_CALENDAR_TOKEN": "/Users/you/creds/token.json"
      }
    }
  }
}

Restart Claude Code and run /mcp to confirm. Call list_calendars as a smoke test. The primary calendar should come back first, followed by any shared calendars.

For team setups, each developer keeps their own token.json. Do not check in a shared token; it is tied to one Google account and the refresh cycle will break in confusing ways.

Configuring for Cursor

Cursor uses the same MCP spec and reads from ~/.cursor/mcp.json. The JSON is identical to the Claude Code config. Paste the same block under mcpServers.

Open Cursor settings, navigate to the MCP tab, and toggle the server on. Cursor spawns the subprocess lazily on the first tool call. Cold start is about 3 seconds, steady state calls land in 200 to 500 ms.

Example prompts and workflows

A few prompts that work well:

• "List my events for next Tuesday between 9am and 5pm."
• "Find me three 30-minute slots this week where Alex and I are both free after 2pm Pacific."
• "Create a 45-minute meeting titled Q2 review with bob@acme.com on Thursday at 10am."
• "Delete the Standup event on Friday and notify attendees."
• "Give me a rundown of every meeting I had last week and highlight anything I rescheduled."

The model will chain calls. A scheduling flow usually runs list_calendars, then freebusy for each person, then create_event with the picked slot. Tell the model the time zone up front if you are not in UTC, otherwise it occasionally writes events in GMT and you end up meeting yourself at 3am.

One pattern that saves calls: pre-filter by date range. Saying next Tuesday triggers a single list_events with timeMin and timeMax set to that day, instead of a broader week-long fetch.

Troubleshooting

Tool call returns 401. The token expired and the refresh token is missing or revoked. Re-run the auth helper script to regenerate token.json.

Tool call returns 403. The Calendar API is not enabled on the Google Cloud project. Open APIs & Services > Library and confirm it is enabled. If the error mentions scopes, widen the OAuth consent screen to include https://www.googleapis.com/auth/calendar.

Tool call returns 404 on a known event. The event is on a calendar the token does not have access to. Run list_calendars and confirm the calendar ID is in the visible set. Shared calendars sometimes need re-acceptance.

Create event succeeds but no invite is sent. The sendUpdates parameter defaults to none in the API. Ask Claude to set sendUpdates=all explicitly in the tool call, or pass it through a system prompt.

Quick add gets the year wrong. Google's natural-language parser assumes the current year unless specified. For events more than 30 days out, include the year in the string to avoid accidental 2025 bookings.

Alternatives

A few options if the Google Calendar server does not fit:

• microsoft-graph-mcp covers Outlook, Teams, and the Office 365 calendar stack under a single OAuth flow.
• cal-com-mcp targets Cal.com for teams already using that as their booking layer.
• ics-mcp is a lighter read-only option that parses any public .ics URL without needing OAuth.

For one-off exports, the ical CLI or a direct API call is often quicker than spinning up an MCP session. The server pays off when scheduling becomes part of a longer Claude workflow, like weekly review prep or inbound lead routing.

The Google Calendar MCP server is the right default for anyone whose day lives inside a Google Calendar. Ten minutes of OAuth setup buys back hours every month in scheduling friction. Start with a single calendar, confirm the read path works, then widen scopes and add write tools as you gain confidence in the prompt patterns.