# 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](https://github.com/travisthetrashpanda/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.

## 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](https://docs.astral.sh/uv/) (`brew install uv` on macOS).

```sh
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](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):
   ```sh
   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:
   ```sh
   claude mcp add --scope user google -- uv run --directory ~/multi-google-calendar-gmail-mcp python server.py
   ```
   or in a JSON MCP config:
   ```json
   {
     "mcpServers": {
       "google": {
         "command": "uv",
         "args": ["run", "--directory", "/Users/YOU/multi-google-calendar-gmail-mcp", "python", "server.py"]
       }
     }
   }
   ```

## Tools

| Area | Tools |
|---|---|
| Accounts | `accounts_list`, `check` |
| Gmail | `gmail_search` (full Gmail query syntax), `gmail_read`, `gmail_labels`, `gmail_modify` (batch label/archive/mark-read, ≤500 ids), `gmail_draft`, `gmail_send` |
| Calendar | `calendar_list`, `calendar_events`, `calendar_create_event` (with attendee invitations) |

Test any tool from the command line:

```sh
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`:

```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](https://github.com/travisthetrashpanda/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](https://github.com/travisthetrashpanda) is always
appreciated — and if you build something on top of it, a link back here
helps others find it.

## License

MIT