<img src="assets/icon/icon.svg" alt="" width="96" height="96">

# 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](https://github.com/Vinksj/claude-gmail-multi). The code is written from scratch.

Project pages: [home](https://efk44.github.io/multiple-gmail/) and
[privacy policy](https://efk44.github.io/multiple-gmail/privacy.html).

## 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

| Tool | What it does |
|---|---|
| `list_accounts` | Shows connected accounts and their status |
| `search_threads` | Gmail search syntax; works on one account or `"all"` |
| `get_thread`, `get_message` | Read a conversation or a message (plain text by default) |
| `list_drafts` | Lists drafts; one account or `"all"` |
| `create_draft` | Creates a draft or a reply draft. It never sends |
| `send_message` | Sends a new message, a reply, or an existing draft |
| `reply` | Sends a reply in a thread |
| `list_labels` | Lists labels; one account or `"all"` |
| `label_thread`, `unlabel_thread` | Adds or removes labels on a thread |

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

## 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](https://github.com/EFK44/multiple-gmail/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.

| System | File |
|---|---|
| Windows (x64) | `multiple-gmail-windows-x64.exe` |
| macOS, Apple Silicon (M1 and later) | `multiple-gmail-macos-arm64.zip` (the app) or `multiple-gmail-macos-arm64` (Terminal only) |
| macOS, Intel | `multiple-gmail-macos-x64.zip` (the app) or `multiple-gmail-macos-x64` (Terminal only) |

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](https://github.com/EFK44/multiple-gmail/issues) 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](https://github.com/EFK44/multiple-gmail/issues) 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.

```sh
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](https://console.cloud.google.com/auth/verification).
   **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](https://developers.google.com/identity/protocols/oauth2/production-readiness/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](https://support.google.com/cloud/answer/13463073)). 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:

```sh
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](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](https://console.cloud.google.com/auth/verification) 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](https://search.google.com/search-console): Add property > URL prefix >
  HTML file or meta tag. Wait 24 hours, then open the [Branding page](https://console.cloud.google.com/auth/branding),
  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

| System | Data folder |
|---|---|
| Windows | `%LOCALAPPDATA%\multiple-gmail` |
| macOS | `~/Library/Application Support/multiple-gmail` |
| Linux | `$XDG_DATA_HOME/multiple-gmail`, usually `~/.local/share/multiple-gmail` |

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](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](LICENSE)