multiple-gmail

All your Gmail accounts, in your AI apps.

multiple-gmail is a small program for Windows and macOS (a Linux version is in development) that lets AI apps such as Claude, Gemini CLI, Cursor or VS Code work with several Gmail accounts at once (personal Gmail and Google Workspace). It runs on your own computer, asks Google for access with your own Google Cloud project, and stores everything encrypted on your disk. Nothing goes to any server of mine.

Inspired by Vinksj/claude-gmail-multi. The code is written from scratch.

Project pages: home and privacy policy.

What it does

You start multiple-gmail (on Windows, double-click multiple-gmail.exe). A setup wizard opens as a tab in your default browser and walks you through the one-time Google setup and connecting your accounts. After that, any AI app that speaks MCP (Model Context Protocol) can use all your connected accounts. Every tool takes an account argument, and searching can run on "all" accounts at once.

Tools

The tools follow the same names and parameters as Claude's official Gmail connector, plus the account argument.

Related MCP server: BedVibe Mail Bridge

Safety model

• No delete tools. There is no tool to delete, trash or empty anything: not mail, not drafts, not labels.

• Sending needs your approval. send_message and reply are marked as destructive and their descriptions tell the AI to use them only after you approved that exact message. The recommended flow is: create a draft, you look at it, then send it.

• Smallest useful permission. Only the gmail.modify scope is requested. It covers reading, drafting, sending and labeling. Google also requires it for changing labels on a thread. The permission to delete mail permanently (https://mail.google.com/) is never requested.

• Everything stays local. The local server listens on 127.0.0.1 only, requires a secret key, and checks the Host and Origin headers. Tokens and your OAuth client are encrypted with AES-256-GCM. The encryption key is protected by DPAPI for your user account on Windows, kept in your login Keychain on macOS, and kept in the Secret Service keyring (GNOME Keyring, KWallet) on Linux when secret-tool is installed. Without secret-tool it is a file in the data folder that only your user can read, and multiple-gmail prints a warning once.

• Removing an account is possible only in the wizard or on the command line. An AI cannot disconnect accounts.

Install

Download the file for your system from Releases. Each file is a single program with everything inside; there is nothing else to install. SHA256SUMS.txt on the same page lets you check the download.

The Windows build is the one I use every day. The macOS builds are built and tested by CI; they are not hand-tested on a Mac yet. Please open an issue if something does not work.

Starting the program a second time does not start another server: it opens the wizard of the running one.

Windows

1. Download multiple-gmail-windows-x64.exe, rename it to multiple-gmail.exe if you like, and put it in a folder in your user profile.

2. Double-click it. The program is not code-signed, so Windows SmartScreen may say "Windows protected your PC". Click More info, then Run anyway.

A console window shows its status. Closing that window stops the server.

macOS

1. Download multiple-gmail-macos-arm64.zip (Apple Silicon: Apple menu > About This Mac shows "Apple M...") or multiple-gmail-macos-x64.zip (Intel). Double-click the zip to unpack multiple-gmail.app.

2. Drag multiple-gmail.app into your Applications folder before the first start. Claude Desktop, Claude Code and Start at login remember where the app is, and a copy started from Downloads runs from a temporary place.

3. Double-click it. The app is not notarized by Apple (that needs a paid Apple developer account), so macOS says it cannot check the app. Click Done (or OK), open System Settings > Privacy & Security, scroll down to "multiple-gmail.app was blocked" and click Open Anyway, then confirm with your password. This is needed once. (On macOS 14 and earlier, right-clicking the app and choosing Open also works.)

4. A Terminal window opens and shows the status, and the wizard opens in your default browser. Closing that Terminal window stops the server, like the console window on Windows.

Prefer Terminal? Download multiple-gmail-macos-arm64 or multiple-gmail-macos-x64 instead, put it for example in ~/Applications/multiple-gmail, run chmod +x ~/Applications/multiple-gmail and xattr -d com.apple.quarantine ~/Applications/multiple-gmail once, then start it with ~/Applications/multiple-gmail.

On first use the encryption key is stored in your login Keychain as multiple-gmail-master-key. If macOS asks whether security may use that Keychain item, choose Always Allow; choosing Deny stops multiple-gmail from reading your saved accounts (it never makes a new key in that case). If your login Keychain is locked, the first start can wait for a Keychain unlock prompt, which may be behind other windows: unlock the Keychain (Keychain Access, or log in again), or set MULTIPLE_GMAIL_MASTER_KEY to skip the Keychain entirely.

Linux

In development. There is no download for Linux yet. If you want to try it early, build from source (below) and open an issue if something does not work.

Updating

1. Fully quit Claude Desktop (on Windows also from the system tray; on macOS Claude > Quit Claude or Cmd+Q) and quit any other AI app that uses multiple-gmail, then close the multiple-gmail window. On Windows a running copy locks the exe, so it cannot be replaced while Claude Desktop or the server window still runs it.

2. Replace the file with the new download at the same path and with the same file name (rename the download the way you renamed the first one). Claude Desktop, Claude Code, Gemini CLI and Start at login store that exact path; a new path or name means they start nothing. If you did move it, open the wizard from the new location and click Update (or the add button) for each app. On macOS, drag the new multiple-gmail.app into Applications and choose Replace.

3. Start multiple-gmail again, then Claude Desktop.

The release notes list anything else that changed.

Build from source

You need Node.js 24 and npm.

npm ci
npm test
npm run build:exe

The result is build/multiple-gmail.exe on Windows and build/multiple-gmail on macOS and Linux, plus build/multiple-gmail.app on macOS. You built it yourself, so the SmartScreen or Gatekeeper warnings above are expected.

Google Cloud setup (once)

Google must know that your copy of multiple-gmail may use Gmail. You tell it in Google Cloud. It is free and needs no credit card. The wizard shows these same steps with direct links; this is the short version. Google changes its website now and then, so a name may differ slightly.

1. Create a project at https://console.cloud.google.com/projectcreate (any name, for example multiple-gmail).

2. Turn on the Gmail API for that project: https://console.cloud.google.com/apis/library/gmail.googleapis.com and click Enable.

3. Describe your app. Open https://console.cloud.google.com/auth/overview and click Get started. Use any app name, your email as support and contact email, and Audience External. Accept the user data policy.

4. Fill in the branding links. Open the Branding page. Under App domain, fill Application home page, Application privacy policy link and Authorized domains, then Save. Google keeps the Publish button disabled until these are set. If you have no website, use this project's public pages:

   • Application home page: https://efk44.github.io/multiple-gmail/

   • Application privacy policy link: https://efk44.github.io/multiple-gmail/privacy.html

   • Authorized domain: efk44.github.io

   If you own a domain, you may use your own instead.

5. Allow Gmail access. Open Data access, click Add or remove scopes, and under Manually add scopes paste https://www.googleapis.com/auth/gmail.modify. Add to table, Update, Save.

6. Create the key file. Open https://console.cloud.google.com/auth/clients and click Create client. Application type Desktop app. If you see a checkbox Use this client for an AI-powered agent, tick it. Click Create, then Download JSON and keep the file.

7. Publish the app. Open Audience and click Publish app, then Confirm. If the button is disabled, hover over it: it tells you what is missing, almost always the Branding fields from step 4. Afterwards Google Cloud shows a yellow "Your app requires verification" banner and a Verification Center. Do not submit the app for verification and ignore that banner. Nothing else is needed.

   Why: Gmail access is a restricted scope, and full verification of such an app is meant for apps that many other people use (restricted scope verification). For personal use with your own client the app works unverified, for up to 100 users per OAuth client (about unverified apps). The only difference is the "Google hasn't verified this app" screen when you sign in (see below).

   Alternative without publishing: stay in Testing mode and add every Gmail address you want to use under Audience > Test users. In Testing mode Google expires the sign-in every 7 days, so each account will show Reconnect in the wizard weekly.

When you later sign in, Google will say "Google hasn't verified this app". That is expected, because the app is yours. Click Advanced, then Go to (your app name) (unsafe). If the Gmail permission checkbox is empty, tick it.

Add your accounts

In the wizard, upload the JSON file, then type any name you like for the account (up to 40 characters, for example Work or İş Hesabı) and click the Google sign-in button. Repeat for each account. Names are matched without regard to case, and all is reserved. You can rename an account later in the control panel. Your AI can refer to an account by its name or by its email address.

The same thing works from a terminal:

multiple-gmail accounts list
multiple-gmail accounts add --name "Work"
multiple-gmail accounts reconnect work
multiple-gmail accounts rename work "Shop"
multiple-gmail accounts remove "Shop"

On Windows the program is multiple-gmail.exe. Unless its folder is on your PATH, give the full path, for example:

• Windows (PowerShell): & "$env:USERPROFILE\Apps\multiple-gmail.exe" accounts list

• macOS: /Applications/multiple-gmail.app/Contents/MacOS/multiple-gmail accounts list (the app) or ~/Applications/multiple-gmail accounts list

• Linux: ~/.local/bin/multiple-gmail accounts list

Connect your AI app

The last wizard step does most of this with a button. By hand:

• Claude Desktop: the wizard has an "Add to Claude Desktop" button. It makes a backup of claude_desktop_config.json first and adds the server without touching your other settings. Fully quit Claude Desktop before you click the button (Claude Desktop may rewrite its config file when it quits, which would undo the change), then start it again afterwards.

• Claude Code: run the command the wizard shows, which has this form: claude mcp add --scope user multiple-gmail -- "C:\path\to\multiple-gmail.exe" --stdio (on macOS and Linux, the path of the multiple-gmail program instead). The wizard can also run it for you.

• Gemini CLI: the wizard can add the server to ~/.gemini/settings.json (with a backup). By hand, add a multiple-gmail entry under mcpServers whose command is the absolute path of the program and whose argument is --stdio, for example {"command": "C:\\Users\\<you>\\Apps\\multiple-gmail.exe", "args": ["--stdio"]} on Windows (backslashes doubled in JSON) or {"command": "/home/<you>/.local/bin/multiple-gmail", "args": ["--stdio"]} on Linux (on macOS, for example /Applications/multiple-gmail.app/Contents/MacOS/multiple-gmail).

• Other apps (Cursor, VS Code, LM Studio, and so on): use the HTTP address http://127.0.0.1:47110/mcp and the header Authorization: Bearer <your local key>. The wizard shows ready-to-copy JSON with your key. The HTTP server runs while the exe is running.

• ChatGPT and claude.ai in the browser cannot reach a program on your computer. For those, run multiple-gmail on a server you control. See DEPLOY.md.

Problems

• Branding verification issues / "The website of your home page URL ... is not registered to you". Google shows this when you submit branding verification for a home page on a domain you do not own, such as the shared efk44.github.io/multiple-gmail pages. You do not need verification, so do not submit it and ignore the Verification Center banner; the app works unverified (see step 7 above). If you use your OWN domain for the branding pages and want the name and logo verified, first prove ownership in Google Search Console: Add property > URL prefix > HTML file or meta tag. Wait 24 hours, then open the Branding page, choose "I have fixed the issues" and click Proceed. Users of the shared pages cannot prove ownership of that domain and should simply not request verification.

• An account says "needs reconnect". Google signed it out, most often because the app is still in Testing mode (7 days) or you changed the account password. Click Reconnect in the wizard and sign in again.

• Google says the app is blocked by your administrator. Your Google Workspace admin blocks unverified apps. They can mark your client as trusted in Admin console > Security > Access and data control > API controls > Manage third-party app access. The wizard shows these steps when it detects the block.

• "This setup link has expired or was already used". Each setup link works once, and the browser uses it right away. Close that tab and open multiple-gmail again: it opens a fresh tab (if it is already running, the new tab may appear in another browser window). To get a link to paste by hand, run multiple-gmail --print-url (multiple-gmail.exe on Windows).

• Port in use. The default port is 47110. Change port in config.json in the data folder (see config.example.json) and start again.

• Claude Desktop does not show the tools. Fully quit Claude Desktop (also from the tray) and start it again. Check that claude_desktop_config.json contains multiple-gmail. The wizard keeps timestamped backups next to that file, so you can restore one if something looks wrong. The Microsoft Store version of Claude Desktop (3.x) keeps its config in %LOCALAPPDATA%\Claude-Data\claude_<id>\claude_desktop_config.json; the installer version uses %APPDATA%\Claude\claude_desktop_config.json. The wizard writes to whichever of these exist. On macOS the file is ~/Library/Application Support/Claude/claude_desktop_config.json (quit with Cmd+Q). On Linux the wizard offers this only when ~/.config/Claude exists.

• SmartScreen blocks the exe. More info, then Run anyway (see Install).

• MULTIPLE_GMAIL_HOME on a USB stick, SD card or network drive. Not supported: the data folder must be on a local disk whose file system supports hard links (NTFS, APFS, ext4 and similar). FAT32, exFAT and network shares (SMB, NFS) are not supported.

Where your data lives, and how to uninstall

Set MULTIPLE_GMAIL_HOME to use another folder. It holds config.json (no secrets) and your encrypted OAuth client and tokens. On Windows it also holds the DPAPI-protected key; on Linux without secret-tool it holds master.key. On macOS the key is the Keychain item multiple-gmail-master-key (remove it in Keychain Access to uninstall); with secret-tool on Linux it is the keyring entry labeled multiple-gmail.

To remove everything:

1. Remove each account in the wizard (or accounts remove <name>). This also asks Google to revoke the token.

2. Delete the data folder.

3. Check https://myaccount.google.com/permissions and remove your app if it is still listed.

4. Delete the program. If you turned on "Start with Windows" ("Start at login" on macOS and Linux), turn it off first in the wizard. It adds ~/Library/LaunchAgents/io.github.efk44.multiple-gmail.plist on macOS and ~/.config/autostart/multiple-gmail.desktop on Linux, and takes effect at your next login.

5. Optionally delete the Google Cloud project.

Server mode

For web AI apps, multiple-gmail can run on your own server behind HTTPS with OAuth 2.1 and an admin password. This is optional and separate from the desktop program. See DEPLOY.md.

Support

Privacy policy: https://efk44.github.io/multiple-gmail/privacy.html . Issues and questions: https://github.com/EFK44/multiple-gmail/issues .

License

MIT