mcp-google-calendar

# <img src="./assets/a1-logo.svg" alt="A1" width="40"> Google Calendar MCP

**English** | [Русский](./README.ru.md)

[![npm](https://img.shields.io/npm/v/%40a1-x-tech%2Fmcp-google-calendar)](https://www.npmjs.com/package/@a1-x-tech/mcp-google-calendar)
[![Glama](https://glama.ai/mcp/servers/A1-x-Tech/mcp-google-calendar/badges/score.svg)](https://glama.ai/mcp/servers/A1-x-Tech/mcp-google-calendar)
[![CI](https://github.com/A1-x-Tech/mcp-google-calendar/actions/workflows/ci.yml/badge.svg)](https://github.com/A1-x-Tech/mcp-google-calendar/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)

**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.

- **19 tools.** Inspect calendars, events and free/busy, create and edit events, expand recurring series, and block Out of Office and Focus Time — plus six for connecting your Google account.
- **Sign in from the chat.** No credentials file to hand-write: ask the assistant to connect, approve access in the browser, and the very next request works — no restart. The client secret travels as a file path, never through the conversation.
- **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](#quick-start) · [Explore use cases](#what-you-can-ask-it-to-do) · [Open technical documentation](#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](#quick-start)
- [What you can ask it to do](#what-you-can-ask-it-to-do)
- [How an event changes](#how-an-event-changes)
- [What can change](#what-can-change)
- [Getting access](#getting-access)
- [Configuration](#configuration)
- [Data, limits and background work](#data-limits-and-background-work)
- [Technical documentation](#technical-documentation)
- [Support](#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](#getting-access).
2. Add the server to your AI app.
3. Ask the read-only question above.

<details open>
<summary><strong>Codex</strong></summary>

<br>

**In the app:** open **Settings → MCP servers**, select **Add server**, choose **STDIO**, enter the command `npx -y @a1-x-tech/mcp-google-calendar@latest` and environment variables `GOOGLE_CALENDAR_CLIENT_ID`, `GOOGLE_CALENDAR_CLIENT_SECRET`, `GOOGLE_CALENDAR_REFRESH_TOKEN`, then select **Save** and **Restart**.

**From the command line:**

```bash
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
```

```bash
codex mcp list
```

[Codex MCP documentation](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)

</details>

<details>
<summary><strong>Claude Code</strong></summary>

<br>

```bash
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
```

```bash
claude mcp list
```

[Claude Code MCP documentation](https://code.claude.com/docs/en/mcp)

</details>

<details>
<summary><strong>Claude Desktop</strong></summary>

<br>

The current official path is **Settings → Extensions**. For a custom desktop extension, open **Advanced settings → Extension Developer → Install Extension…**, select a `.mcpb` file and follow the prompts.

This repository currently publishes an npm stdio package and does not contain a `.mcpb` bundle. For Claude Desktop builds that still support local configuration, use the following JSON stdio configuration as a fallback:

```json
{
  "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"
      }
    }
  }
}
```

In those builds, save it to `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows.

[Claude Desktop MCP documentation](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop)

</details>

<details>
<summary><strong>Cursor</strong></summary>

<br>

Add this to `~/.cursor/mcp.json` on macOS/Linux or `%USERPROFILE%\.cursor\mcp.json` on Windows:

```json
{
  "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"
      }
    }
  }
}
```

[Cursor MCP documentation](https://cursor.com/docs/mcp)

</details>

<details>
<summary><strong>VS Code</strong></summary>

<br>

Run **MCP: Open User Configuration** and add:

```json
{
  "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 }
  ]
}
```

Check it with **MCP: List Servers**.

[VS Code MCP documentation](https://code.visualstudio.com/docs/agent-customization/mcp-servers)

</details>

## 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

| Operation | What happens | Confirmation boundary |
|---|---|---|
| Read calendars, events and free/busy | Reads schedule data; free/busy shows busy blocks without titles | No change |
| Create an event | Adds a timed, all-day or recurring event, optionally with guests and Google Meet | Changes a calendar |
| Create an Out of Office or Focus Time block | Adds a special event that can auto-decline invitations or silence Google Chat | Changes a calendar |
| Update an event | Reschedules or edits an event; a series id edits every occurrence | Changes a calendar |
| Move an event | Re-homes an event to another calendar | Changes two calendars |
| Delete