multi-mail-mcp

Local-first MCP server for agents that need to work across multiple Gmail and Microsoft 365 accounts without cloud token storage.

This is an alpha built for the exact pain in the thread: work Gmail, personal Gmail, side-project Gmail, and Microsoft 365 should all be available to an agent by alias.

Beta site: https://multi-mail-mcp.netlify.app

What It Does

• Stores multiple accounts as local aliases: work, personal, side, m365, etc.

• Encrypts OAuth profiles and tokens on the machine.

• Exposes one MCP server over stdio.

• Supports Gmail and Microsoft 365 / Outlook.

• Searches one account or all accounts.

• Fetches Gmail threads or Microsoft 365 conversations.

• Creates drafts.

• Sends drafts or new emails only when the tool call includes confirm: "SEND".

Tools

• list_accounts

• search_mail

• get_thread

• create_draft

• send_draft

• send_mail

Install

npm install -g https://github.com/claygeo/multi-mail-mcp/archive/refs/heads/main.tar.gz
mailmcp init

Add Gmail

Create a Google OAuth desktop client, then run:

node dist/cli.js add-gmail `
  --alias personal `
  --client-id "<GOOGLE_CLIENT_ID>" `
  --client-secret "<GOOGLE_CLIENT_SECRET>"

Default Gmail scopes:

• https://www.googleapis.com/auth/gmail.readonly

• https://www.googleapis.com/auth/gmail.compose

That means read/search plus draft/send support. There is no delete/archive/label mutation tool in this alpha.

Add Microsoft 365

Create a Microsoft Entra public/native app with a localhost redirect URI, then run:

node dist/cli.js add-m365 `
  --alias work `
  --client-id "<MICROSOFT_CLIENT_ID>" `
  --tenant common

Default Microsoft scopes:

• offline_access

• User.Read

• Mail.Read

• Mail.ReadWrite

• Mail.Send

Some work/school tenants require admin consent before delegated mail scopes work.

MCP Client Config

Use this server as a stdio MCP command:

{
  "mcpServers": {
    "multi-mail": {
      "command": "node",
      "args": ["C:\\Users\\clayg\\Documents\\Codex\\2026-05-27\\caleb-baskin-calebbaskin-6m-i-ll\\dist\\cli.js", "server"]
    }
  }
}

If installed globally later, this can become:

{
  "mcpServers": {
    "multi-mail": {
      "command": "mailmcp",
      "args": ["server"]
    }
  }
}

Example Agent Prompts

List my configured mail accounts.

Search all my mail accounts for "invoice from Stripe" and show the newest 10 hits.

Use my work account to draft a reply to this thread. Do not send it.

Send the draft from my personal account only if it matches the body we just approved.

Security Shape

The alpha is intentionally local-first:

• Tokens are encrypted in profiles.vault.json.

• The vault key is generated locally as master.key, or derived from MAILMCP_MASTER_KEY if set.

• No email contents or tokens are sent to this package's servers because there are no package servers.

• Send operations require confirm: "SEND".

• Delete/archive/label mutation tools are intentionally absent.

For a production public release, replace the local key-file fallback with OS keychain storage and complete the relevant Google/Microsoft verification work.

Verification

npm run check

This runs the TypeScript build and local smoke tests. OAuth/API calls require real client credentials and user login.