Multi-Gmail Connector for Claude

Free · Local-first · Open source · Read-only

Let Claude search and read several Gmail accounts at once (personal, business, accounting…) from Claude Desktop or Claude Code. Every result tells you which account it came from.

"Search all my connected inboxes for my Emirates flight confirmation." → Found in Personal (personal@gmail.com): "Your Emirates flight confirmation EK202", 3 Sep.

It runs on your own computer. You use your own Google credentials, and your tokens stay in your operating system's keychain. The authors run no server and never see your passwords, tokens, emails or searches.

Status: first public release (v0.2.0). The code and its 113 automated tests are green on Linux, macOS and Windows in CI, and the connector has been in daily use on Windows with two Gmail accounts. Real-account setup on macOS and Linux has not been walked through yet — if something there is wrong, please open an issue.

Contents

What it does · Supported environments · Privacy · Security · Install · Google Cloud setup · Multiple accounts · The weekly re-sign-in · Commands · Example prompts · Troubleshooting · Uninstall · Limitations · Roadmap

Related MCP server: gmail-mcp

What it does

• Connects any number of Gmail accounts (up to 25) under one Claude connector.

• Gives Claude five read-only tools:

It cannot send, reply, forward, delete, archive, move, label, draft, or mark emails read/unread. Google is only asked for the gmail.readonly permission.

Supported environments

Privacy model

• Runs locally; there is no server and no telemetry.

• Your Google OAuth client, refresh tokens and settings stay on your machine.

• Email content goes only from Google to Claude, and only when Claude calls a tool in your conversation.

• Nothing is cached to disk except the non-secret account list (config.json).

Details: docs/PRIVACY.md.

Security model

• Tokens in the OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service). They are never stored in plaintext, never logged, and never given to Claude.

• Minimum permission: gmail.readonly, plus openid email to identify each account.

• OAuth best practice: loopback redirect on 127.0.0.1, PKCE (S256), state and nonce checks, ID-token validation.

• Accounts are identified by Google's permanent account id, not by email address.

• Email is treated as untrusted: hidden HTML text and invisible characters are removed, suspicious "instructions to the AI" are flagged, and output is size-limited.

• Account changes happen only in your terminal, never through Claude.

⚠️ Prompt injection: an email can contain text designed to manipulate an AI. This connector is read-only and labels email content as untrusted, but no filter catches everything. Be careful combining email search with other tools that can send data or take actions in the same Claude session, and keep approval prompts on for those tools. See docs/SECURITY_DESIGN.md.

Install

You need Node.js 22+ and a Google account. Two commands:

npm install -g multi-gmail-connector
cmec setup

cmec setup is the whole installation: it checks Node.js and your keychain, walks you through the Google Cloud pages one at a time, imports your OAuth client, connects your accounts, tests Gmail access, and writes the configuration into Claude Desktop and Claude Code for you. Restart Claude Desktop at the end and the email tools are there.

Later, npm update -g multi-gmail-connector upgrades it.

git clone https://github.com/goodyoss-byte/multi-gmail-connector.git
cd multi-gmail-connector
npm install
npm run build     # npm 11+ no longer runs the build itself
npm link          # optional: puts the `cmec` command on your PATH
cmec setup

If you skip npm link, every cmec <command> in this README is npm run cmec -- <command> instead, run from this folder. Keep the folder: a source install launches from it, so moving or deleting it breaks the connector. A global install has no such folder.

Google Cloud setup

You need your own (free) Google Cloud project with the Gmail API and a Desktop app OAuth client. cmec setup opens each page in order and waits for you; cmec google-setup runs just that walkthrough again. The written version, with screenshots of what to expect, is in docs/GOOGLE_CLOUD_SETUP.md.

1. Create a Google Cloud project.

2. Enable the Gmail API.

3. Configure the OAuth consent screen (External, Testing mode; add your Gmail addresses as test users under Audience).

4. Create an OAuth client of type Desktop app and download its JSON.

5. No redirect URIs are needed.

6. Setup finds the downloaded file in your Downloads folder, or you can paste the client ID and secret. It is stored in your keychain and the file can then be deleted.

Why not a shared client? A shared one would put the project's credentials in every copy of the code and require Google's paid security assessment, because Gmail read access is a restricted scope. Your own client keeps you in control. See ADR-0013.

Connecting multiple Gmail accounts

cmec add --label Personal
cmec add --label Business
cmec add --label Accounting
cmec list

Each command opens your browser; pick a different Google account each time. Because the app is your own unverified app, Google shows "Google hasn't verified this app" once per account. Choose Advanced → Go to … (unsafe), then make sure "Read your email" is ticked.

The weekly re-sign-in

While your OAuth app stays in Testing mode, Google expires its sign-ins after 7 days. That is Google's rule, not this connector's. Two things make it painless:

• cmec fix checks every account and re-signs in only the ones that need it, in one pass.

• list_email_accounts reports how long ago each account was signed in, so Claude can warn you before a search fails.

Leaving Testing mode removes the weekly expiry, but Google's Publish app button needs an application home page, a privacy policy and an authorised domain you own — so for most personal installs, cmec fix once a week is the simpler trade. See docs/GOOGLE_CLOUD_SETUP.md.

Commands

cmec setup                     # everything: Google client, accounts, and add it to Claude
cmec add [--label NAME]        # connect another account
cmec list                      # show accounts, status and when each was last signed in
cmec fix                       # check everything and renew whatever expired
cmec install                   # (re-)write the Claude Desktop / Claude Code configuration
cmec label Business "Company"  # rename
cmec include Accounting off    # leave out of "search all"
cmec reconnect Personal        # re-authorise one account
cmec remove Accounting         # revoke at Google + delete the stored token
cmec doctor                    # check everything (never shows email content)
cmec claude-config             # print the configuration instead of writing it
cmec uninstall                 # revoke everything and delete all local data

New accounts you connect later appear without restarting Claude.

Example prompts

• "Search all my connected inboxes for my Emirates flight confirmation."

• "Check all my inboxes for unread emails from this week that look important. Group them by account."

• "In my Business account, find invoices from Acme since 1 July and total the amounts from the CSV attachments."

• "Which of my accounts received the password-reset email from my bank?"

• "Show me the whole thread about the office lease."

Troubleshooting

Uninstall and revoking access

cmec uninstall                 # revokes every account at Google, deletes keychain entries and config
claude mcp remove email        # Claude Code (or remove "email" from claude_desktop_config.json)
npm uninstall -g multi-gmail-connector        # or `npm unlink -g multi-gmail-connector` for a source install

You can also revoke access any time at https://myaccount.google.com/permissions, and delete your Google Cloud project in the Console. Details: GOOGLE_CLOUD_SETUP.md §10–11.

Limitations

• Read-only; no sending or organising mail.

• Gmail only for now (Outlook planned).

• Claude Desktop and Claude Code only; not the web or mobile apps.

• Text attachments only (no PDF/Office text extraction yet).

• Search uses Gmail's own search; results per call are capped at 25 (ask for "more results" for the next page).

• Setup needs a terminal and a Google Cloud project.

• Prompt-injection detection is heuristic (see above).

Roadmap

PDF and Office attachment text → a drag-and-drop Claude Desktop extension (.mcpb) so no terminal is needed → Gmail labels as a filter → Outlook / Microsoft 365. See docs/IMPLEMENTATION_ROADMAP.md. A hosted edition may exist in future for people who don't want to run anything locally; this edition will keep working on its own.

Documentation

Architecture · Diagrams · OAuth · MCP tools · Provider design · Security design · Threat model · Privacy · Testing · Decisions (ADRs) · Research notes · Changelog

Contributing and security

See CONTRIBUTING.md. Report vulnerabilities privately as described in SECURITY.md, not in public issues.

License

Copyright (C) 2026 goodyoss-byte

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License, version 3 (AGPL-3.0-only), as published by the Free Software Foundation. It is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See LICENSE for the full text.

In short: you can use, study, change and share it for free. If you distribute a modified version, or offer a modified version to others as an online service, you must make your full source code available under the same licence. Running it privately on your own computer carries no obligations.

Not affiliated with, endorsed by, or sponsored by Anthropic or Google. "Claude" is a trademark of Anthropic, PBC and "Gmail" and "Google" are trademarks of Google LLC; both are used here only to say what this software works with.