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

In Google Cloud Console:

1. Enable the Gmail API.
2. Configure the OAuth consent screen. While the app is in testing, add the Gmail account as a test user.
3. Create an OAuth client with application type Desktop app.

Then run:

mailmcp add-gmail `
  --alias personal `
  --credentials-json "C:\Users\you\Downloads\client_secret_....apps.googleusercontent.com.json"

The local callback is http://127.0.0.1:41577.

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

In Microsoft Entra:

1. Register an app.
2. Add a Mobile and desktop applications platform redirect URI: http://127.0.0.1:41578/oauth/callback.
3. Enable public client/native flows for the app registration.

Then run:

mailmcp 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.

Verify The Full Loop

After at least one account is added:

mailmcp list
mailmcp verify --account personal --max-results 3
mailmcp verify --account personal --max-results 3 --draft-to you@example.com

verify checks the local vault, confirms the send guard refuses sends without confirm: "SEND", searches real mail, fetches the first returned thread/conversation, and optionally creates an unsent draft. It does not send email.

If you added both providers:

mailmcp verify --provider gmail --max-results 3
mailmcp verify --provider m365 --max-results 3

To prove the MCP layer itself is responding:

npx @modelcontextprotocol/inspector --cli mailmcp server --method tools/list
npx @modelcontextprotocol/inspector --cli mailmcp server --method tools/call --tool-name list_accounts

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.
• On Windows, init and vault writes try to remove inherited ACLs from the config directory, vault, and key so only the current user, Administrators, and SYSTEM can read them.
• 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.