multi-google-calendar-gmail-mcp

One small Python file that gives Claude (or any MCP client) Gmail and Google Calendar across as many Google accounts as you want — a personal Gmail, three Workspace domains, whatever. Each account gets a nickname; every tool takes a nickname or "all" to sweep the whole fleet in one call.

"find every unread invoice across all five inboxes and label them Bookkeeping" — one tool call.

Why this one

• Multi-account is the whole design, not a bolt-on. Most self-hosted Gmail MCPs authenticate one account. Here, connecting another account is one command + one browser click, and cross-account operations are native.

• Minimal. One readable server.py, three dependencies. If you want to know what it does, you can just read it.

• Bring your own credentials. Nothing is hosted, nothing phones home. You create your own (free) Google Cloud OAuth client, and your account keys live in a git-ignored folder on your machine. This repo never sees them.

Pairs naturally with apple-suite-mcp: that one reads whatever your Mac's built-in apps already see (zero setup, macOS only); this one speaks Google's APIs directly (real labels, batch operations up to 500 messages, drafts, calendar invites with attendees) and runs anywhere Python runs — including a headless Linux box.

Related MCP server: mcp-google-multi

Setup

Easy mode — let your AI install it

If you use Claude Code (or any coding agent), paste this and let it drive:

Read https://github.com/travisthetrashpanda/multi-google-calendar-gmail-mcp and install it for me: clone it, walk me through the one-time Google Cloud credential setup in its SETUP.md, help me connect my accounts with its connect command, and register it with my MCP client.

The agent handles the fiddly parts and can diagnose failures with the built-in check command; you just click Allow in the browser when Google asks. (Sensible to read what you're installing first — it's one Python file.)

Manual mode

Requires uv (brew install uv on macOS).

git clone https://github.com/travisthetrashpanda/multi-google-calendar-gmail-mcp.git ~/multi-google-calendar-gmail-mcp

1. One-time Google Cloud setup (~15 min, free): follow SETUP.md — create a Cloud project, enable the Gmail and Calendar APIs, publish the consent screen (avoids 7-day token expiry), create a Desktop-app OAuth client, and drop credentials.json in this folder. Heads-up: Google rejects app names containing the word "Google".

2. Connect the accounts you choose (repeat per account, any alias you like — only accounts you connect are ever visible):

   cd ~/multi-google-calendar-gmail-mcp
   uv run python server.py connect work
   uv run python server.py connect personal

   Changed your mind? uv run python server.py disconnect work deletes that account's key.

3. Verify: uv run python server.py check

4. Register with your MCP client — e.g. Claude Code:

   claude mcp add --scope user google -- uv run --directory ~/multi-google-calendar-gmail-mcp python server.py

   or in a JSON MCP config:

   {
     "mcpServers": {
       "google": {
         "command": "uv",
         "args": ["run", "--directory", "/Users/YOU/multi-google-calendar-gmail-mcp", "python", "server.py"]
       }
     }
   }

Tools

Test any tool from the command line:

uv run python server.py test gmail_search '{"query": "is:unread", "account": "all", "limit": 5}'

Scoping access (optional)

You already control access by choosing what to connect — but if you want a client to see only a subset of connected accounts (or to remove tools entirely), copy config.example.json to config.json:

{
  "accounts": ["work", "personal"],
  "disabled_tools": ["gmail_send"]
}

Accounts not listed become invisible to every tool; tools in disabled_tools are never even registered with the MCP client. Omit a key (or the whole file) to allow everything. check reports active scoping.

Safety notes

• There is deliberately no delete/trash tool — the most destructive operation is archiving (removing from inbox), which is reversible.

• gmail_send and attendee invitations send real email; MCP clients should confirm with the user first.

• credentials.json and tokens/ are git-ignored. Treat the tokens/ folder like passwords — don't put it in cloud-synced directories.

Credits

Sibling project of apple-suite-mcp; the two split the work of giving an AI assistant a complete view of your accounts — locally-visible vs. API-native.

Say thanks

This project is free to use, no strings attached. If it's useful to you, a ⭐ on this repo or a shout-out to @travisthetrashpanda is always appreciated — and if you build something on top of it, a link back here helps others find it.

License

MIT