# 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

```powershell
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:

```powershell
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:

```powershell
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:

```powershell
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:

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

To prove the MCP layer itself is responding:

```powershell
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:

```json
{
  "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:

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

## Example Agent Prompts

```text
List my configured mail accounts.
```

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

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

```text
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

```powershell
npm run check
```

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