mailmux

Free, self-hosted multi-mailbox agentic inbox.
Connect any IMAP/SMTP mail. One unified inbox in the browser. One MCP surface for every agent.

No paid SaaS required for core receive + send. MIT licensed.

Quick start

cd Projects/mailmux   # or your clone path
npm install
./scripts/start.sh --fixture
# equivalent: npm run dev -- --fixture

Open http://127.0.0.1:8787 — on localhost the UI auto-loads the bearer token.

Fixture mode seeds two demo mailboxes (personal, work) so you can try the UI and MCP without real credentials.

Real mail

npm run dev

In the UI: Connect mailbox → pick a preset (Gmail / Fastmail / Outlook / iCloud) or enter IMAP/SMTP hosts → use an app password where required.

Production-ish start

npm run build
npm start
# or: node dist/cli.js serve

Related MCP server: mail-mcp

Using the hosted interface

mailmux has one web interface: the Next.js app in apps/web, built as a static export. You can serve it from your own process or host it elsewhere. Either way it talks to the mailmux server on your machine, and it never sends your mail or your token anywhere else.

Local (recommended — works in every browser)

npm run build
npm start

npm run build compiles the server, builds apps/web, and copies the export to web-next/. Open the URL it prints, normally http://127.0.0.1:8787. Same origin as the API, so nothing else is needed.

To run it on its own during development:

cd apps/web && npm install && npm run dev     # http://localhost:3000
cd apps/web && npm run build && npm run serve # the real static export

Hosted (deployed somewhere else)

The page runs entirely in your browser and fetches mail directly from your machine.

1. Deploy apps/web. On Vercel and equivalents, set the project's Root Directory to apps/web and leave the build and output commands on auto. That setting is what keeps the CLI's better-sqlite3 out of the front-end install; it lives in the dashboard and cannot be expressed in a file. Do not add a workspaces key to the root package.json.

No environment variable is required. One optional, non-secret variable exists:

2. Allow the origin. On your machine, not on the host:

MAILMUX_ALLOWED_ORIGINS=https://your-deployment.example.com mailmux serve

See the rules and the cost of doing this under Browser origins below.

3. Copy the token. mailmux serve prints it on first run; it is also in bearer.token inside your data directory (~/.mailmux by default).

4. Point the page at your server. Open the deployed page, click Set up mailmux, and enter the Server URL and the token. Both are stored in your browser's localStorage and are sent only to the server URL you entered.

5. Allow local network access (Chrome, Edge, Brave). Since Chromium 142 the browser asks permission before a website may reach 127.0.0.1. Allow it when prompted; if you dismissed the prompt, re-enable it under Site settings → Apps on device.

Safari, and the mixed-content limit

A page served over https cannot reach an http address. For 127.0.0.1 and localhost Chromium and Firefox make an exception; WebKit does not, and there is no workaround (WebKit bug 171934, still open). This is also why MAILMUX_ALLOWED_ORIGINS drops http:// entries: the configuration that would avoid the block is the one that makes the allowlist spoofable.

If your server is not on loopback, put it behind https or reach it over a tunnel. Otherwise use the local build — run mailmux serve and open http://127.0.0.1:8787 directly. It is the same interface.

What the host can see

Nothing. The deployed page has no server-side code: no API routes, no server actions, no proxy, no middleware. Your token, your mail credentials and every message body travel only between your browser and your own machine.

Agent MCP (any client)

HTTP MCP (Cursor / remote-capable clients)

{
  "mcpServers": {
    "mailmux": {
      "url": "http://127.0.0.1:8787/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Token lives in ~/.mailmux/bearer.token (or MAILMUX_TOKEN).

stdio MCP (Claude Desktop / Claude Code)

npm run mcp
# or: npx tsx src/cli.ts mcp

{
  "mcpServers": {
    "mailmux": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/mailmux/src/cli.ts", "mcp"],
      "env": {
        "MAILMUX_DATA_DIR": "/Users/you/.mailmux"
      }
    }
  }
}

Tools

Accounts are connected once in the web UI (or API). Agents reuse the same store — no per-agent OAuth.

Install options

Env

Browser origins (MAILMUX_ALLOWED_ORIGINS)

By default mailmux accepts browser requests only from your own machine. A page on any other origin gets 403 {"error":"forbidden origin"}. Leave the variable unset and nothing changes.

Set it when you want a web interface hosted somewhere else — a deployment of apps/web, for example — to talk to your local server. The page still runs entirely in your browser and still fetches mail directly from your machine; the variable only tells your server which page origins it will answer. See Using the hosted interface for the full walkthrough.

MAILMUX_ALLOWED_ORIGINS=https://your-deployment.example.com mailmux serve

Rules:

• Comma-separated, exact origins. https://a.example.com,https://b.example.com.

• Only https:// entries are kept. A plaintext origin is trivially spoofed on a hostile network, so http:// entries are dropped.

• Path, query and case are stripped: https://A.App/x becomes https://a.app. A port must match exactly — https://a.app does not allow https://a.app:8443.

• * is ignored on purpose. mailmux holds your mail credentials; an any-origin allowlist would let any page you visit probe your server.

• Loopback (127.0.0.1, localhost, ::1) always passes, so the self-hosted UI needs no configuration.

• Requests with no Origin header (curl, MCP clients) are unaffected.

What enabling this costs you. The origin check is the last defence-in-depth layer in front of a service that holds decrypted IMAP passwords. Adding an origin means:

• Anyone who can serve a page at that exact hostname can reach your server if they also have your bearer token. On shared hosting platforms that includes preview deployments and anyone with deploy access. Prefer a custom domain you control over a platform-assigned hostname.

• It is the only remaining barrier against a DNS-rebinding page reaching your loopback service, so the list should stay as short as you can make it.

• The token is still required on every request. Access-Control-Allow-Credentials is never sent — mailmux authenticates by header, never by cookie — so no page can ride ambient credentials.

• /api/local-bootstrap, which hands out the bearer token in plaintext, is not widened by this variable. It stays loopback-only. A remote page must have its token pasted in by a human.

Architecture

See docs/ARCHITECTURE.md.

One Node process:

• / — web UI (the apps/web export, served from web-next/)

• /api/* — REST (same mail core)

• /mcp — JSON-RPC MCP

• mailmux mcp — stdio MCP

IMAP via ImapFlow, SMTP via Nodemailer, secrets AES-256-GCM, state SQLite.

Tests

npm test

Tests call shipped MailService, crypto, HTTP app, and MCP handlers with an in-memory FixtureProvider — no live mail accounts required.

Security notes

• Default bind is localhost.

• Browser requests are loopback-only unless MAILMUX_ALLOWED_ORIGINS names another origin. Default is closed.

• Passwords encrypted at rest; master key in ~/.mailmux/master.key (mode 0600).

• Prefer app passwords over primary account passwords.

• Keep message_send behind agent confirmation.

License

MIT — free to use, modify, and redistribute.