Content
# gmail-multi-mcp
Connect **multiple Gmail accounts** to Claude (or any [MCP](https://modelcontextprotocol.io)
client) from one local server. The official Gmail connector only supports a single Google
account — this lets you search, read, draft, send, label, and organize mail across as many
accounts as you like, each addressed by a friendly alias.
Your OAuth tokens are stored **locally on your machine only** — never uploaded anywhere.
## Features
- 🔢 **Unlimited accounts** — every tool takes an `account` parameter (`"personal"`, `"work"`, …)
- 🔎 **Search & read** — full Gmail search syntax, thread/message reading, attachment download
- ✍️ **Compose** — create/list/delete drafts, send mail, replies with correct threading headers
- 🏷️ **Organize** — full label management, archive, trash
- 🔐 **Local-first** — standard Google OAuth; tokens live in `~/.gmail-mcp/`, chmod 600
- 🧩 **22 tools**, works with Claude Code, Claude Desktop, Cursor, and any MCP client
## Prerequisites
- **Node.js ≥ 20**
- A Google account (and a free Google Cloud project — setup below)
## 1. Install
```bash
git clone https://github.com/Vinksj/claude-gmail-multi.git
cd claude-gmail-multi
npm install
npm run build
```
## 2. Create your Google OAuth app (one-time, ~10 min)
You register one OAuth "app" with Google; it then works for all the accounts you connect.
1. Go to [console.cloud.google.com](https://console.cloud.google.com) → create a project (e.g. `gmail-mcp`).
2. **APIs & Services → Library** → search **Gmail API** → **Enable**.
3. **APIs & Services → OAuth consent screen**:
- User type **External** → Create.
- App name + your support email + your contact email → Save and Continue.
- Scopes page → Save and Continue. Test users page → Save and Continue.
4. **Publish to production:** on the OAuth consent screen, set **Publishing status → Publish app**.
*(In "Testing" mode Google expires your refresh token every 7 days. Publishing avoids that.
You'll click through a one-time "Google hasn't verified this app" warning per account — that's
normal for a personal app: choose **Advanced → Continue**.)*
5. **APIs & Services → Credentials → Create Credentials → OAuth client ID**:
- Application type **Desktop app** → Create → **Download JSON**.
6. Save that file as `~/.gmail-mcp/credentials.json`:
```bash
mkdir -p ~/.gmail-mcp && chmod 700 ~/.gmail-mcp
mv ~/Downloads/client_secret_*.json ~/.gmail-mcp/credentials.json
chmod 600 ~/.gmail-mcp/credentials.json
```
> Note: newer Google Cloud UIs put these under **"Google Auth Platform"** (Branding / Audience /
> Clients) instead of "OAuth consent screen" — same steps, different labels.
## 3. Connect your accounts
```bash
npm run auth -- --alias personal --email you@gmail.com
npm run auth -- --alias work --email you@company.com
```
Each opens a browser → pick the matching Google account → approve. The optional `--email` flag
aborts if the wrong account gets authorized (an easy mistake with multi-login browsers). Connect
as many as you want; re-run any time a token is revoked.
## 4. Register with your MCP client
**Claude Code:**
```bash
claude mcp add --scope user gmail-multi -- node "$(pwd)/dist/index.js"
```
**Claude Desktop / other clients** — add to your MCP config:
```json
{
"mcpServers": {
"gmail-multi": {
"command": "node",
"args": ["/absolute/path/to/gmail-multi-mcp/dist/index.js"]
}
}
}
```
Tools appear as `gmail-multi`'s `search_threads`, `create_draft`, etc. Ask things like
*"search my work inbox for unread from this week"* or *"draft a reply in personal to Alice."*
## Tools
| Group | Tools |
|---|---|
| Accounts | `list_accounts`, `add_account` |
| Read | `search_threads`, `get_thread`, `get_message`, `download_attachment` |
| Compose | `create_draft`, `list_drafts`, `delete_draft`, `send_draft`, `send_message` |
| Labels | `list_labels`, `create_label`, `update_label`, `delete_label`, `label_thread`, `unlabel_thread`, `label_message`, `unlabel_message` |
| Cleanup | `archive_thread`, `trash_thread`, `trash_message` |
Every tool except `list_accounts` takes an `account` parameter (alias or email). Replies via
`replyToMessageId` get correct `In-Reply-To`/`References` headers and threading automatically.
## How it works
- One self-owned Google Cloud OAuth app (Desktop client) authorizes any number of accounts.
- Single scope: `https://www.googleapis.com/auth/gmail.modify` (read, search, drafts, send,
labels, archive, trash — narrower than full `https://mail.google.com/`).
- Per-account refresh tokens stored in `~/.gmail-mcp/tokens/<alias>.json` (chmod 600); the
account registry is `~/.gmail-mcp/config.json`. Nothing leaves your machine.
```
~/.gmail-mcp/
├── credentials.json # your OAuth client (you add this)
├── config.json # alias → email map (auto-managed)
└── tokens/<alias>.json # per-account refresh tokens (auto-managed)
```
## Security notes
- Tokens are stored as plain files readable only by your user (chmod 600). On a single-user
machine with full-disk encryption this is reasonable; moving token storage to the OS keychain
is a sensible future hardening step.
- Never commit `~/.gmail-mcp/` — it lives in your home directory, outside this repo, and the
repo's `.gitignore` excludes build artifacts and dependencies regardless.
- The `gmail.modify` scope cannot permanently delete mail — `trash_*` tools move items to Trash
(recoverable for 30 days).
## Development
```bash
npm run build # tsc -> dist/
npm run inspect # MCP Inspector UI against the built server
npm run auth -- --alias <name> [--email <expected>]
```
Important: stdout is the JSON-RPC channel — never `console.log` in server code; use `console.error`.
## License
MIT © Saurabh Jain
