pombus

Pombus MCP server

Email boxes for AI agents — the opposite of a webmail client. Pombus gives a person and their AI agents their own mailboxes; the agent operates the mailbox over the Model Context Protocol while the human stays in the loop.

This package is the MCP server: a thin stdio translator between a client's MCP tool calls and the Pombus REST API. It holds no mail and no logic of its own — every read, draft and send is a call to the Pombus core. Learn more at pombus.com.

Install

One command wires Pombus into your MCP client:

npx pombus init

init reads your API key, detects your client, and writes the MCP server block into its config (merging, never clobbering the rest of the file). Detected clients: Claude Code, Cursor, Gemini CLI, and Codex CLI (Codex uses TOML, so init prints the block for you to paste).

npx pombus init --print                 # print the config block, write nothing
npx pombus init --client cursor         # target one client
npx pombus init --create-inbox          # create an inbox during setup

Commands

Command	What it does
pombus mcp	Run the stdio MCP server. Your client invokes this; you rarely do.
pombus init	Write the Pombus MCP config into your client.
pombus doctor	Validate your API key and report its scope. Read-only, one request.

Authentication

Set POMBUS_API_KEY in the environment. init writes it into the MCP server block for you; the key never lands in your terminal scrollback. Get a key at pombus.com.

{
  "mcpServers": {
    "pombus": {
      "command": "npx",
      "args": ["-y", "pombus", "mcp"],
      "env": { "POMBUS_API_KEY": "<YOUR_POMBUS_API_KEY>" }
    }
  }
}

The tools are gated by your key

The server exposes a catalog of 53 tools — list and read threads, search, label, compose and send drafts, manage lists, read metrics. But your API key decides what the agent actually sees. A tool is only registered when the key holds the permission that tool needs; a key without send permission never sees a send tool, so the agent cannot call it. The same key also fixes the scope: an inbox-scoped key binds a single inbox, and tools drop the inbox_id argument entirely — the agent physically cannot address another inbox.

Draft-first is the default write path. Composing a message creates a draft (create_draft) for a human to review; sending is a separate, explicit step (send_draft). Direct, unreviewed send exists only for keys that explicitly hold send permission — most keys stay draft-only.

Run pombus doctor to see exactly which scope your key resolves to.

License

MIT © Runaki