{
  "markdown": "# multi-gmail-mcp\n\nA [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.\n\n![demo](multi-gmail-demo.gif)\n\n---\n\n## Features\n\n- Connect **unlimited Gmail accounts** — personal, work, side projects\n- **Search** any inbox using full Gmail search syntax\n- **Read** complete emails with MIME parsing\n- **Send**, **reply in thread**, and **create drafts**\n- **Organize** with labels: add, remove, list, archive\n- **Mark as read / unread**\n- Tokens stored locally in `~/.gmail-mcp-tokens.db` — never committed to git\n- Auto-refreshes OAuth tokens silently\n\n---\n\n## Requirements\n\n- Node.js >= 22.5.0\n- A Google Cloud project with the Gmail API enabled\n- Claude Desktop\n\n---\n\n## Installation\n\n```bash\nnpm install -g multi-gmail-mcp\n```\n\nThis registers two global commands: `gmail-mcp` (the MCP server) and `gmail-mcp-cli` (account manager).\n\n---\n\n## Google Cloud Setup\n\nYou only need to do this once.\n\n1. Go to [console.cloud.google.com](https://console.cloud.google.com) → create a project\n2. Enable the **Gmail API** (APIs & Services → Library)\n3. Configure the **OAuth consent screen** — External, add your Gmail addresses as test users\n4. Add scopes: `gmail.readonly`, `gmail.send`, `gmail.modify`, `gmail.labels`\n5. Create a **Desktop app** OAuth credential → download the JSON\n6. Save it to `~/.gmail-mcp-oauth.json`\n\nAlternatively, set environment variables in the Claude Desktop config (see below).\n\n---\n\n## Authenticating Gmail Accounts\n\n```bash\n# Add accounts (opens browser for Google sign-in)\ngmail-mcp-cli add personal@gmail.com\ngmail-mcp-cli add work@company.com\n\n# List authenticated accounts\ngmail-mcp-cli list\n\n# Remove an account\ngmail-mcp-cli remove work@company.com\n```\n\nTokens are saved to `~/.gmail-mcp-tokens.db` and refreshed automatically.\n\n---\n\n## Claude Desktop Configuration\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"multi-gmail\": {\n      \"command\": \"gmail-mcp\"\n    }\n  }\n}\n```\n\nIf you prefer environment variables over `~/.gmail-mcp-oauth.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"multi-gmail\": {\n      \"command\": \"gmail-mcp\",\n      \"env\": {\n        \"GOOGLE_CLIENT_ID\": \"your-client-id.apps.googleusercontent.com\",\n        \"GOOGLE_CLIENT_SECRET\": \"your-client-secret\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop after saving. Click the hammer icon to confirm 19 tools are loaded.\n\n---\n\n## Available Tools\n\n### Account Management\n\n| Tool | Description |\n|---|---|\n| `list_accounts` | List all authenticated Gmail accounts |\n| `initiate_auth` | Start OAuth flow — returns a URL to open in browser |\n| `complete_auth` | Finalize auth after completing Google sign-in |\n| `remove_account` | Remove an account and its stored credentials |\n\n### Reading Email\n\n| Tool | Description |\n|---|---|\n| `search_emails` | Search with Gmail syntax (`is:unread`, `from:`, `after:`, etc.) |\n| `get_email` | Fetch full email content by message ID |\n\n### Writing Email\n\n| Tool | Description |\n|---|---|\n| `send_email` | Send an email (supports To, CC, BCC) |\n| `reply_to_email` | Reply in thread, preserving References headers |\n| `create_draft` | Save an email as a draft |\n\n### Organization\n\n| Tool | Description |\n|---|---|\n| `list_labels` | List all Gmail labels for an account |\n| `add_label` | Add one or more labels to a message |\n| `remove_label` | Remove one or more labels from a message |\n| `archive_email` | Remove from Inbox |\n| `mark_as_read` | Remove the UNREAD label |\n| `mark_as_unread` | Add the UNREAD label |\n\n---\n\n## Example Prompts\n\n```\nList all my authenticated Gmail accounts.\n```\n\n```\nSearch my work@company.com inbox for unread emails from this week.\n```\n\n```\nReply to that email from my personal account saying I'll be there Saturday.\n```\n\n```\nSend an email from personal@gmail.com to friend@example.com\nwith subject \"Dinner plans\" and body \"Are you free Saturday?\"\n```\n\n```\nArchive everything older than a week in my side-project inbox that's already read.\n```\n\n```\nCheck both my accounts for emails from GitHub and summarize them.\n```\n\n---\n\n## Security\n\n- `~/.gmail-mcp-oauth.json` and `~/.gmail-mcp-tokens.db` live in your home directory — outside the project, never committed\n- `.gitignore` excludes `*.db`, `.gmail-mcp-oauth.json`, and `.env`\n- The server runs over **stdio only** — no network port is opened\n- OAuth scopes are limited to the minimum required\n\nSee [SECURITY.md](SECURITY.md) for full details: token storage, network behavior, scope rationale, revocation steps, and how to report a vulnerability.\n\n---\n\n## Registry\n\nListed on the official Anthropic MCP registry:\n\n```\nio.github.gx-55/multi-gmail-mcp\n```\n\n```bash\ncurl \"https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.gx-55\"\n```\n\n---\n\n## Project Structure\n\n```\nmulti-gmail-mcp/\n├── bin/\n│   ├── gmail-mcp.js        # Entry point for the MCP server command\n│   └── gmail-mcp-cli.js    # Entry point for the CLI command\n├── src/\n│   ├── server.js           # MCP server — all 19 tools\n│   ├── gmail-client.js     # Gmail API wrapper\n│   ├── auth.js             # OAuth2 flow with auto-refresh\n│   ├── db.js               # SQLite token storage (node:sqlite)\n│   └── cli.js              # Account management CLI\n└── package.json\n```\n\n---\n\n## Troubleshooting\n\n**\"No OAuth credentials found\"**\nMake sure `~/.gmail-mcp-oauth.json` exists or set `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` in the Claude Desktop config.\n\n**\"Account not found. Authenticate it first\"**\nRun `gmail-mcp-cli add your@gmail.com` before using that account in Claude.\n\n**Tools not appearing in Claude Desktop**\nConfirm `gmail-mcp` is in your PATH (`which gmail-mcp`) and restart Claude Desktop.\n\n**Token expired errors**\nTokens 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`.\n",
  "bytes": 6027,
  "sha": "bd24f88401cfdfd38c963beac7bfeb3248f5357157102cfcd31ac2ed1d07082e",
  "repo_slug": "gx-55/multi-gmail-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_gx_55_multi_gmail_mcp_ad97b24a/readme"
}