Pombus MCP Server
Official# 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](https://modelcontextprotocol.io) 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](https://pombus.com).
<!-- mcp-name: com.pombus/pombus -->
## Install
One command wires Pombus into your MCP client:
```sh
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).
```sh
npx pombus init --print # print the config block, write nothing
npx pombus init --client cursor # target one client
npx pombus init --create-inbox --domain acme.com # create an inbox on YOUR verified domain
```
`--create-inbox` needs `--domain`: an extra inbox can only be created on a domain
you own and have verified in Pombus. (Your account's `@pombus.com` inbox is the one
from signup; an API key cannot create more of those —
`403 platform_inbox_not_allowed`.)
## 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](https://pombus.com).
Without a key, `pombus mcp` still starts, for introspection only: it lists the
tool catalog, and every tool call returns a "POMBUS_API_KEY is not set" error.
It makes no network request until a key is set.
```json
{
"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](./LICENSE) © Runaki
TDQS
Scored across 53 tools
Each tool targets a resource+action pair and descriptions actively disambiguate the risky cases (create_draft vs send_draft vs send_message vs reply_message; trash_message vs delete_message vs delete_thread). The remaining overlap is mild but real: list_messages / list_sent / list_threads / search_messages / search_threads all return mail-like streams and an agent must read descriptions to choose correctly.
Names follow a strict verb_noun snake_case pattern across every sub-resource (list_pods, create_domain, verify_domain, delete_webhook, test_webhook), with no camelCase or bare-verb outliers. The only wart is `list_list_entries`, which reads awkwardly but still conforms to the same convention.
53 tools is heavy for any single agent surface and forces context bloat plus tool-selection load. The breadth is genuinely justified by the domain (pods, inboxes, messages, domains, labels, allow/block lists, metrics, API keys, webhooks each with a full CRUD set), so it is heavy rather than padded, but it sits well past the comfortable scoping range.
CRUD/lifecycle coverage is strong: mail read/search/label/trash/restore/delete, draft-then-send, plus full create/update/delete for domains, inboxes, labels, list entries, API keys and webhooks, with verification and metrics. Minor gaps remain: no update_pod, no single-inbox get, and attachments only expose metadata/URL with no list or upload path.