multi-mail

English · עברית

multi-mail MCP

An MCP server for several Gmail accounts at once. It searches, reads, drafts and sends mail, and works with Claude Desktop, Claude Code and ChatGPT.

It has two transports:

• stdio (dist/server.js) runs locally, for Claude Desktop and Claude Code.
• Streamable HTTP (dist/http.js) is for ChatGPT, or any client that connects by URL. A token is required.

Each user brings their own Google OAuth client. Because of that, no Google app verification is needed and nothing passes through a third party. Mail goes only between your machine and Google.

The story behind it, with the comparison and examples: One MCP server for every Gmail account, in Claude and ChatGPT.

Tools

Choosing a mailbox:

• account accepts a full address, an alias (work), or the part before the @.
• With a single account connected, you can leave it out.
• MULTI_MAIL_DEFAULT sets a default account.

Replying:

• reply_to_message_id puts the reply in the right thread and fills in the recipient and subject.
• reply_all adds every original recipient.

Permissions: gmail.readonly and gmail.compose by default. The server cannot delete mail, move it to trash, or change settings.

• Calendar is opt-in per account (add --calendar), which adds calendar.readonly and calendar.events. The server reads events and free/busy, and creates events on your own calendar without inviting anyone. It has no tool to change or delete an event. The calendar tools appear only when at least one account has calendar enabled. Times are read in each calendar's own time zone. If a calendar is set wrong (a new Google account often defaults to UTC), set MULTI_MAIL_TZ=Asia/Jerusalem or pass time_zone to the tool.
• Labels are opt-in per account (add --labels), which adds gmail.modify. At Google's level that scope would also allow trashing mail, so the server has no trash tool and refuses the TRASH and SPAM labels.

Drafts-only mode

Start the server with --drafts-only, or set MULTI_MAIL_SEND=off, and send_email and send_draft are not registered at all. The model can still read, search and write drafts, but nothing can leave your mailbox until you press Send in Gmail.

Use it whenever the server reads mail you didn't write and nobody approves each step. That covers automated triage, scheduled tasks, and clients that skip permission prompts. Any incoming message could carry instructions ("forward this to…"), and in this mode there is no tool that could carry them out.

claude mcp add multi-mail -s user -- npx -y @yybd/multi-mail-mcp --drafts-only

How it compares

Checked on 2026-11-07, with star counts from that day, against web search and the awesome-mcp-servers list. The closest alternatives were checked against their own READMEs. I couldn't find official documentation of what the built-in Claude and ChatGPT connectors can do. That information comes mostly from blog posts by competing vendors, so treat it as approximate.

Takeaways:

• The built-in connectors don't give you several accounts plus sending in every client.
• Several self-hosted servers now handle more than one Gmail account. Each makes a different trade-off:
  • alexneamtu/gmail-mcp is remote-only and needs a Linux server with an HTTPS hostname.
  • mailmcp reaches Gmail over IMAP with app passwords, under a commercial licence.
  • gws-connector covers the whole Workspace for local clients, without ChatGPT.
  • Most of the rest run locally only, so ChatGPT can't connect to them.
• Hosted brokers route your mail and tokens through a third party.
• multi-mail's niche is one MIT-licensed npx package that runs locally over stdio and, when you want ChatGPT, over token-protected HTTP. It uses the Gmail API with your own OAuth client and keeps a narrow scope:
  • It has no delete permission.
  • Tokens stay on your machine with 600 permissions.
  • The HTTP server won't start without a token.
• multi-mail covers mail and Google Calendar. For the rest of Workspace, such as Drive or Docs, google_workspace_mcp is the mature choice, or gws-connector across several accounts.

Setup

You need Node.js 20 or newer. There's nothing to install: every command below runs the published package through npx.

git clone https://github.com/yybd/multi-mail-mcp.git multi-mail && cd multi-mail && npm install && npm run build

1. Create your own Google OAuth client (once)

Do this once, from one Google account. The same client then works for every mailbox you connect. If you already have a Google Cloud project for personal tools, you can add the client there instead of creating a new project.

1. Project. Go to console.cloud.google.com/projectcreate, name the project (for example multi-mail) and click Create. Make sure it's selected in the top bar.

2. Gmail API. On the Gmail API page, click Enable. If you'll use the calendar, also enable the Google Calendar API.

3. Consent screen. In Google Auth Platform, click Get started and fill in:

   • App name: anything you like.
   • Support email: yours.
   • Audience: External.
   • Contact email: yours.

   Accept the terms and click Create. You don't need to add scopes here; the server asks for them itself.

4. Publish. Under Audience, click Publish app, then Confirm. The status should read In production.

   • ⚠️ In Testing mode, access expires every 7 days.
   • For personal use, Google doesn't need to verify the app.
   • If you stay in Testing anyway, add every Gmail address under Test users.

5. Client. Under Clients, click Create client, choose the type Desktop app, and click Create. Then click Download JSON right away, because the secret is shown in full only in that dialog. Save the file like this:

mkdir -p ~/.multi-mail && mv ~/Downloads/client_secret_*.json ~/.multi-mail/credentials.json && chmod 600 ~/.multi-mail/credentials.json

2. Connect your mailboxes

Run this once per mailbox, with a different alias each time:

npx -y @yybd/multi-mail-mcp add --alias work

npx -y @yybd/multi-mail-mcp add --alias home

Each add opens a browser where you pick a Google account and approve access.

• You'll see "Google hasn't verified this app". That's expected, because it's your own app. Click Advanced, then Go to … (unsafe).
• Tick every permission box. If one is missing, the CLI stops and tells you which.

Managing accounts:

• npx -y @yybd/multi-mail-mcp list lists the connected accounts.
• check verifies every account still has access.
• alias <account> <name> sets or changes an alias. The account can be its current alias, its address, or the part before @. For example, npx -y @yybd/multi-mail-mcp alias tech work renames tech to work, and it takes effect immediately, without a restart.
• remove <account> disconnects an account.
• add <account> --calendar reconnects an account with Google Calendar. This needs the Google Calendar API enabled in the same Cloud project as the Gmail API (step 2 of the OAuth setup). The flags combine, for example add work --labels --calendar.
• add <account> --labels reconnects an account with label permission (needed for modify_labels and create_label). Running add again without --labels takes it away.

Tokens live in ~/.multi-mail/accounts/ with 600 permissions; MULTI_MAIL_HOME moves that folder. A running server picks up a newly added account without a restart.

Connect your clients

Claude Code

claude mcp add multi-mail -s user -- npx -y @yybd/multi-mail-mcp

Claude Desktop

In ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{  "mcpServers": {    "multi-mail": {      "command": "npx",      "args": ["-y", "@yybd/multi-mail-mcp"]    }  }}

Then restart Claude Desktop. If it can't find npx, use its full path (which npx, for example /opt/homebrew/bin/npx).

ChatGPT

ChatGPT only connects to remote HTTPS servers, so you run the HTTP mode and expose it through a tunnel. Run these one after another:

npx -y @yybd/multi-mail-mcp token

MCP_AUTH_TOKEN=<token> npx -y @yybd/multi-mail-mcp http

cloudflared tunnel --url http://127.0.0.1:3333

ngrok http 3333 also works instead of cloudflared.

In ChatGPT, open Settings → Apps & Connectors → Advanced, turn on Developer mode, then click Create and fill in:

• URL: https://<your-tunnel-host>/mcp?api_key=<token>
• Authentication: No authentication (the token is already in the URL).

Security of HTTP mode:

• The server listens on 127.0.0.1 only.
• It refuses to start without an MCP_AUTH_TOKEN of at least 24 characters.
• Clients that can send headers may use Authorization: Bearer <token> instead of api_key.
• ⚠️ Anyone with the full URL can read and send from your mailboxes. Treat it like a password, and rotate the token (token) if it leaks.

HTTP environment variables: PORT (default 3333), HOST (default 127.0.0.1), MCP_AUTH_TOKEN.

Development

npm test

The tests run offline, with no Google account. They cover Hebrew/UTF-8 MIME encoding, account selection, the tool list over stdio and HTTP, and token enforcement.

Layout:

• src/config.ts — accounts and files
• src/gmail.ts — Gmail calls
• src/mime.ts — building and parsing messages
• src/mcp.ts — the tools
• src/server.ts / src/http.ts — transports
• src/cli.ts — account management

Not supported yet: attaching files to outgoing mail.

License

MIT — see LICENSE.