Google Calendar MCP

English | Русский

A1 Google Calendar MCP lets an AI app manage Google Calendar in plain language. Review your week, schedule a meeting with guests and a Google Meet link, reschedule or cancel it, find a slot when everyone is free, and block Out of Office or Focus Time.

It uses the Google Calendar API with your Google account. It distinguishes a whole recurring series from a single occurrence and makes the limits of the Calendar API explicit instead of implying that every calendar task is possible.

• 13 tools. Inspect calendars, events and free/busy, create and edit events, expand recurring series, and block Out of Office and Focus Time.
• Nobody is emailed by accident. The Calendar API's default for invitations, changes and cancellations is silence; guests get email only when you ask for it via send_updates.
• Writes are never replayed. After an ambiguous failure the server does not retry a write — a duplicated event could re-email every guest.
• Minimal Google scopes. It uses calendar.events and calendar.readonly, without the broad calendar scope.

Start with a read-only question:

What's on my calendar this week? Point out any overlapping meetings.

Connect the server · Explore use cases · Open technical documentation

See it work in a minute

You: What does my Thursday look like, and when are Anna and I both free?

Assistant: Shows Thursday's events and the free slots you share. Nothing changes.

You: Book a 45-minute design review with Anna in the first shared slot, with a Google Meet link.

Assistant: Shows the proposed time, guest list and Meet link, then asks for confirmation before creating the event.

You: Confirm.

Assistant: Creates the event. Nobody gets an email unless you ask it to send invitations.

Contents

• Quick start
• What you can ask it to do
• How an event changes
• What can change
• Getting access
• Configuration
• Data, limits and background work
• Technical documentation
• Support

Quick start

You need Node.js 20+, a Google account and OAuth credentials from a Google Cloud project with the Google Calendar API enabled.

1. Prepare Google OAuth access.
2. Add the server to your AI app.
3. Ask the read-only question above.

codex mcp add google-calendar \
  --env GOOGLE_CALENDAR_CLIENT_ID=your_client_id \
  --env GOOGLE_CALENDAR_CLIENT_SECRET=your_client_secret \
  --env GOOGLE_CALENDAR_REFRESH_TOKEN=your_refresh_token \
  -- npx -y @a1-x-tech/mcp-google-calendar@latest

codex mcp list

claude mcp add \
  --env GOOGLE_CALENDAR_CLIENT_ID=your_client_id \
  --env GOOGLE_CALENDAR_CLIENT_SECRET=your_client_secret \
  --env GOOGLE_CALENDAR_REFRESH_TOKEN=your_refresh_token \
  --transport stdio --scope user google-calendar \
  -- npx -y @a1-x-tech/mcp-google-calendar@latest

claude mcp list

{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      "args": ["-y", "@a1-x-tech/mcp-google-calendar@latest"],
      "env": {
        "GOOGLE_CALENDAR_CLIENT_ID": "your_client_id",
        "GOOGLE_CALENDAR_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_CALENDAR_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

{
  "mcpServers": {
    "google-calendar": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@a1-x-tech/mcp-google-calendar@latest"],
      "env": {
        "GOOGLE_CALENDAR_CLIENT_ID": "your_client_id",
        "GOOGLE_CALENDAR_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_CALENDAR_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

{
  "servers": {
    "google-calendar": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@a1-x-tech/mcp-google-calendar@latest"],
      "env": {
        "GOOGLE_CALENDAR_CLIENT_ID": "${input:calendar_client_id}",
        "GOOGLE_CALENDAR_CLIENT_SECRET": "${input:calendar_client_secret}",
        "GOOGLE_CALENDAR_REFRESH_TOKEN": "${input:calendar_refresh_token}"
      }
    }
  },
  "inputs": [
    { "type": "promptString", "id": "calendar_client_id", "description": "Google OAuth client ID" },
    { "type": "promptString", "id": "calendar_client_secret", "description": "Google OAuth client secret", "password": true },
    { "type": "promptString", "id": "calendar_refresh_token", "description": "Google OAuth refresh token", "password": true }
  ]
}

What you can ask it to do

See your schedule

• What meetings do I have this week? Include the recurring ones.
• Show tomorrow's 1:1 with its guests, Meet link and reminders.
• List every occurrence of the team sync in March.

Plan and change meetings

• Create a 45-minute review on Thursday with two guests and a Google Meet link.
• Reschedule the retro one hour later and update the guest list — but don't email anyone yet.
• Move the planning event to the team calendar.
• Cancel Friday's occurrence of the standup, leaving the rest of the series alone.

Protect your time

• When are Anna, Boris and I all free for an hour next week?
• Block Out of Office for my vacation and auto-decline new invitations.
• Create two hours of Focus Time tomorrow morning and silence Google Chat.

How an event changes

1. calendar_id: "primary" is your main calendar; other calendars come from list_calendars, and writes need writer access.
2. A recurring series and a single occurrence have different ids: the series id changes or cancels every occurrence, an instance id (from list_event_instances) exactly one.
3. update_event changes only the fields you provide, but a nested object replaces its predecessor wholesale — a new attendees list replaces the whole guest list.
4. No write emails anybody unless send_updates says so — the Calendar API's default is silence.

Out of Office and Focus Time blocks exist only on the primary calendar of a Google Workspace account; consumer Gmail and secondary calendars reject them. Creating an event does not check for conflicts — ask for a free/busy check first. All-day events end on an exclusive date: an event through Friday ends on Saturday's date.

What can change