multi-google-mcp

A self-hosted, multi-account Google MCP server. One local server exposes Gmail (read + draft) and Google Calendar (read + create/update) across as many Google accounts as you authorize — each addressed per call by an account argument.

Built to get around the single-account limit of hosted Gmail/Calendar connectors: authorize you@gmail.com, you2@gmail.com, … and talk to each by name from one server.

What it does — and deliberately doesn't

Gmail — read + draft only: gmail_list_accounts · gmail_search · gmail_get_thread · gmail_list_drafts · gmail_create_draft · gmail_list_labels · gmail_create_label · gmail_modify_labels

No send tool exists. gmail_create_draft stages a draft; sending stays a human action in Gmail.

Google Calendar — read + write, no delete: calendar_list_calendars · calendar_list_events · calendar_get_event · calendar_create_event · calendar_update_event

No delete tool exists. Create/update default to sendUpdates="none" — attendees are never emailed unless you explicitly pass send_updates ("all" / "externalOnly").

Scopes requested: gmail.readonly, gmail.compose, gmail.modify, gmail.labels, calendar.events, calendar.readonly. gmail.send and the full-access mail.google.com are intentionally not requested.

Related MCP server: MCP Google Workspace Server

Requirements

• Python 3.9+

• A Google Cloud project you control (see setup). A self-hosted app talking to your own Gmail/Calendar needs its own OAuth client — there's no way around this.

Setup

1. Google Cloud (one-time)

1. Create or pick a project in the Google Cloud Console.

2. Enable the Gmail API and the Google Calendar API.

3. Configure the OAuth consent screen (User type: External). Add each Google account you'll authorize as a Test user — or Publish the app to production so refresh tokens don't expire after 7 days. Publishing an External app additionally requires homepage and privacy-policy URLs on the Branding page; since your app's only user is you, just put this repo's URL in all three link fields (any page you stand behind works — domain ownership is only checked at verification, which a personal app never undergoes). No page at all? Stay in Testing (no URLs needed) and re-run authorize.py weekly.

4. Create an OAuth client of type Desktop app and download its JSON from the creation dialog (the interactive setup asks for the file's path), or save it as:

   ~/.config/multi-google-mcp/client_secret.json

   (Windows: %USERPROFILE%\.config\multi-google-mcp\client_secret.json.)

2. Install + configure (interactive)

git clone https://github.com/GoodHabitx/multi-google-mcp
cd multi-google-mcp

# Windows (PowerShell)
./setup.ps1

# macOS / Linux
./setup.sh

Creates .venv/, installs the Google client libraries, then launches the interactive setup (setup.py): it prints each Google Console link (clickable via OSC 8 where the terminal supports it, and copied to the clipboard — reliable even over remote sessions), places the client_secret.json you download, runs the browser consent for each account, and registers the MCP server. Re-run setup.py directly (with the venv python) any time to add an account or redo a step — it's idempotent. Steps 3–4 below are what it automates; Step 1 is the Console work it guides you through.

3. Authorize each account (opens a browser)

# macOS / Linux
.venv/bin/python authorize.py you@gmail.com

# Windows
.venv\Scripts\python.exe authorize.py you@gmail.com

Repeat per account. Tokens are saved (mode 600) under ~/.config/multi-google-mcp/tokens/<email>.json — outside this repo.

4. Register with your MCP client (user scope, per-machine)

claude mcp add google -s user -- /abs/path/.venv/bin/python /abs/path/server.py

Then restart the session so it loads the server. Tools appear as mcp__google__gmail_search, mcp__google__calendar_list_events, etc. (The google name is the server key — pick whatever you like; it becomes the tool prefix.)

Re-authorization

Added a scope after authorizing an account (e.g. Calendar)? Just re-run authorize.py <email> for it — the new consent mints a token carrying the current scopes. Gmail keeps working in the meantime; calendar calls return a clean 403 until the account is re-authorized.

Security

• No secret ever lives in the repo. The OAuth client + per-account tokens live under ~/.config/multi-google-mcp/ (override with MULTI_GOOGLE_MCP_CONFIG_DIR); .gitignore blocks them regardless.

• No gmail.send, no send tool. No events().delete, no delete tool.

• Calendar writes never notify attendees unless send_updates is explicitly set.

Why there's no "one-click" login

A self-hosted app that reads your own Gmail needs its own OAuth client and a consent click. Gmail is a Google "restricted scope" that only a verified app may use seamlessly, and verification is a heavy security assessment that's impractical for a personal tool — so the Google Cloud steps above are the minimum. A maintainer could bundle a shared Desktop-app client so users only "Sign in with Google" (they'd hit an "unverified app" screen); that's intentionally not enabled here.

Tests

.venv/bin/python tests/test_threading.py

Hermetic — no network, no tokens, no real drafts (the Gmail service is faked in-process).

License

MIT — see LICENSE.