gmail-multi-mcp

An open-source MCP server that connects any number of Gmail accounts to Claude (or any MCP client) in one place. Everything runs locally, and your tokens never leave your machine.

Tools

Every tool takes an account argument, which can be the full email address or an alias such as work.

Related MCP server: email-mcp

1. Create a Google OAuth client (once)

1. Open https://console.cloud.google.com/ and create a project.

2. APIs & Services → Library → enable the Gmail API.

3. APIs & Services → OAuth consent screen: choose External and fill in the app name and your email. Under Test users, add every Gmail address you want to connect.

4. APIs & Services → Credentials → Create credentials → OAuth client ID → Desktop app. Download the JSON file.

5. Save the file as ~/.config/gmail-multi-mcp/credentials.json.

Tip: while the app is in Testing status, Google expires refresh tokens after 7 days. For personal use you can click Publish app on the consent screen. It stays unverified, so you'll see an "unverified app" warning when you sign in, but the tokens stop expiring.

One OAuth client works for all your accounts.

2. Install

Install uv. It also installs Python for you:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then install the server straight from GitHub:

uv tool install https://github.com/anitalklausen/gmail-multi-mcp/archive/refs/heads/main.zip

To install from a local clone instead, run uv tool install . in the project folder.

This puts gmail-multi-mcp in ~/.local/bin.

3. Connect accounts

Run this once per account. A browser opens where you choose the Google account:

gmail-multi-mcp add --alias private
gmail-multi-mcp add --alias work
gmail-multi-mcp add --alias shop --read-only
gmail-multi-mcp list

Remove an account with gmail-multi-mcp remove work. New accounts are picked up by the running server without a restart.

4. Add it to Claude

Claude Desktop: go to Settings → Developer → Edit Config and add the server to claude_desktop_config.json:

{
  "mcpServers": {
    "gmail": {
      "command": "/Users/YOUR_USERNAME/.local/bin/gmail-multi-mcp"
    }
  }
}

Use the absolute path, because Claude Desktop does not read your shell's PATH. Restart Claude Desktop afterwards.

Claude Code:

claude mcp add gmail --scope user -- ~/.local/bin/gmail-multi-mcp

Configuration

Security

• Tokens are stored in tokens/<email>.json with 600 permissions. Treat them like passwords.

• The default scope is gmail.modify: read, send, and change labels, but never permanent deletion. Accounts added with --read-only get gmail.readonly.

• The server tells the model to confirm with you before sending, and Claude also asks for approval on every tool call.

See also the privacy policy.

License

MIT