mcp-google-calendar

A minimal MCP server for Google Calendar using OAuth 2.0 and the Google Calendar API.

Tools

• connect_calendar() and calendar_health()

• list_calendars()

• list_events(...) and get_event(...)

• create_event(...), with recurrence, attendees, and optional Google Meet

• update_event(...) and delete_event(...)

• list_calendar_acl(...) and share_calendar(...)

• watch_calendar_events(...)

• list_event_changes(...)

create_event, update_event, delete_event, share_calendar, and watch_calendar_events have external side effects. MCP clients should request explicit confirmation before calling them.

Setup

1. Enable the Google Calendar API in Google Cloud Console.

2. Create an OAuth client with application type Desktop app.

3. Download the OAuth file as credentials.json into this directory.

4. Install dependencies and start the server:

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
python server.py

Authorization is a two-step tool call, so it works the same whether this server runs on your laptop or on a machine with no browser at all:

1. Call google_auth_start. It returns an authorization URL.

2. Approve access in a browser — any browser, on any device.

3. Call google_auth_complete with the URL you land on.

On a desktop, steps 2 and 3 usually happen by themselves: the browser is opened for you and the redirect is caught on http://localhost:8765 (set GOOGLE_OAUTH_PORT to change it).

On a headless server, or when you approve on a phone, that redirect cannot be reached and the browser shows a connection error. That is expected — the authorization code is in the address bar. Copy the whole URL (http://localhost:8765/?code=...) and pass it to google_auth_complete, which also accepts the bare code value.

Both credentials.json and token.json are ignored by Git.

Optional .env configuration:

GOOGLE_CREDENTIALS=credentials.json
GOOGLE_TOKEN=token.json
GOOGLE_CALENDAR_TIMEZONE=Asia/Jakarta

MCP Client

{
  "mcpServers": {
    "google-calendar": {
      "command": "python",
      "args": [
        "C:/Users/your-user/Documents/GitHub/mcp-google-calendar/server.py"
      ]
    }
  }
}