Content
# multi-gmail-mcp
A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that lets **Claude Desktop manage multiple Gmail accounts** simultaneously. Listed on the official Anthropic MCP registry and published on npm.
---
## Features
- Connect **unlimited Gmail accounts** — personal, work, side projects
- **Search** any inbox using full Gmail search syntax
- **Read** complete emails with MIME parsing
- **Send**, **reply in thread**, and **create drafts**
- **Organize** with labels: add, remove, list, archive
- **Mark as read / unread**
- Tokens stored locally in `~/.gmail-mcp-tokens.db` — never committed to git
- Auto-refreshes OAuth tokens silently
---
## Requirements
- Node.js >= 22.5.0
- A Google Cloud project with the Gmail API enabled
- Claude Desktop
---
## Installation
```bash
npm install -g multi-gmail-mcp
```
This registers two global commands: `gmail-mcp` (the MCP server) and `gmail-mcp-cli` (account manager).
---
## Google Cloud Setup
You only need to do this once.
1. Go to [console.cloud.google.com](https://console.cloud.google.com) → create a project
2. Enable the **Gmail API** (APIs & Services → Library)
3. Configure the **OAuth consent screen** — External, add your Gmail addresses as test users
4. Add scopes: `gmail.readonly`, `gmail.send`, `gmail.modify`, `gmail.labels`
5. Create a **Desktop app** OAuth credential → download the JSON
6. Save it to `~/.gmail-mcp-oauth.json`
Alternatively, set environment variables in the Claude Desktop config (see below).
---
## Authenticating Gmail Accounts
```bash
# Add accounts (opens browser for Google sign-in)
gmail-mcp-cli add personal@gmail.com
gmail-mcp-cli add work@company.com
# List authenticated accounts
gmail-mcp-cli list
# Remove an account
gmail-mcp-cli remove work@company.com
```
Tokens are saved to `~/.gmail-mcp-tokens.db` and refreshed automatically.
---
## Claude Desktop Configuration
Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"multi-gmail": {
"command": "gmail-mcp"
}
}
}
```
If you prefer environment variables over `~/.gmail-mcp-oauth.json`:
```json
{
"mcpServers": {
"multi-gmail": {
"command": "gmail-mcp",
"env": {
"GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
"GOOGLE_CLIENT_SECRET": "your-client-secret"
}
}
}
}
```
Restart Claude Desktop after saving. Click the hammer icon to confirm 19 tools are loaded.
---
## Available Tools
### Account Management
| Tool | Description |
|---|---|
| `list_accounts` | List all authenticated Gmail accounts |
| `initiate_auth` | Start OAuth flow — returns a URL to open in browser |
| `complete_auth` | Finalize auth after completing Google sign-in |
| `remove_account` | Remove an account and its stored credentials |
### Reading Email
| Tool | Description |
|---|---|
| `search_emails` | Search with Gmail syntax (`is:unread`, `from:`, `after:`, etc.) |
| `get_email` | Fetch full email content by message ID |
### Writing Email
| Tool | Description |
|---|---|
| `send_email` | Send an email (supports To, CC, BCC) |
| `reply_to_email` | Reply in thread, preserving References headers |
| `create_draft` | Save an email as a draft |
### Organization
| Tool | Description |
|---|---|
| `list_labels` | List all Gmail labels for an account |
| `add_label` | Add one or more labels to a message |
| `remove_label` | Remove one or more labels from a message |
| `archive_email` | Remove from Inbox |
| `mark_as_read` | Remove the UNREAD label |
| `mark_as_unread` | Add the UNREAD label |
---
## Example Prompts
```
List all my authenticated Gmail accounts.
```
```
Search my work@company.com inbox for unread emails from this week.
```
```
Reply to that email from my personal account saying I'll be there Saturday.
```
```
Send an email from personal@gmail.com to friend@example.com
with subject "Dinner plans" and body "Are you free Saturday?"
```
```
Archive everything older than a week in my side-project inbox that's already read.
```
```
Check both my accounts for emails from GitHub and summarize them.
```
---
## Security
- `~/.gmail-mcp-oauth.json` and `~/.gmail-mcp-tokens.db` live in your home directory — outside the project, never committed
- `.gitignore` excludes `*.db`, `.gmail-mcp-oauth.json`, and `.env`
- The server runs over **stdio only** — no network port is opened
- OAuth scopes are limited to the minimum required
See [SECURITY.md](SECURITY.md) for full details: token storage, network behavior, scope rationale, revocation steps, and how to report a vulnerability.
---
## Registry
Listed on the official Anthropic MCP registry:
```
io.github.gx-55/multi-gmail-mcp
```
```bash
curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.gx-55"
```
---
## Project Structure
```
multi-gmail-mcp/
├── bin/
│ ├── gmail-mcp.js # Entry point for the MCP server command
│ └── gmail-mcp-cli.js # Entry point for the CLI command
├── src/
│ ├── server.js # MCP server — all 19 tools
│ ├── gmail-client.js # Gmail API wrapper
│ ├── auth.js # OAuth2 flow with auto-refresh
│ ├── db.js # SQLite token storage (node:sqlite)
│ └── cli.js # Account management CLI
└── package.json
```
---
## Troubleshooting
**"No OAuth credentials found"**
Make sure `~/.gmail-mcp-oauth.json` exists or set `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` in the Claude Desktop config.
**"Account not found. Authenticate it first"**
Run `gmail-mcp-cli add your@gmail.com` before using that account in Claude.
**Tools not appearing in Claude Desktop**
Confirm `gmail-mcp` is in your PATH (`which gmail-mcp`) and restart Claude Desktop.
**Token expired errors**
Tokens auto-refresh if a valid refresh token is stored. If refresh fails, remove the account and re-authenticate: `gmail-mcp-cli remove your@gmail.com && gmail-mcp-cli add your@gmail.com`.
