postfach-mcp

A self-hosted remote MCP server that gives an AI assistant read-focused access to any IMAP mailbox: search, read, create drafts, light triage. Postfach is German for mailbox.

Deliberately no send, no delete — by design, not by configuration. E-mail is untrusted third-party input; an assistant that reads it can be manipulated by it. This server keeps the blast radius small: the worst a hijacked session can do is file a draft, create a folder or move a message — all of it sits in your mailbox, in plain sight, reversible. A send tool may appear in a later version, but only behind an explicit opt-in flag, unregistered by default. Feature requests to weaken this stance will be declined.

Status

v0.2.0 — in production use by the author against a real IMAP mailbox, with three client paths verified: Claude Code, claude.ai on the web, and the Claude Android app. Still a 0.x: the tool surface and configuration may change between releases. Changes are tracked in CHANGELOG.md.

Related MCP server: imap-mcp

Tools

Messages are addressed by folder + uid; UIDs are per-folder. Reading never sets the seen flag — only mark_read does, when asked.

Installation

Requires Python 3.11+.

pip install git+https://github.com/unstko/postfach-mcp

Or from a clone: pip install . — both install the postfach-mcp command.

Configuration

Everything is environment variables prefixed POSTFACH_MCP_; a commented template is in .env.example. Missing or invalid variables are reported together, each by name.

Running

postfach-mcp check   # probe the IMAP login, list folders, verify the drafts folder
postfach-mcp serve   # run the HTTP server (--host/--port override the environment)

check is the deploy diagnosis: it answers "are the credentials right, and what is the drafts folder actually called on this server?" without starting anything. serve exposes the MCP endpoint at /mcp and an unauthenticated health probe at /api/health.

Connecting clients

Any Streamable-HTTP MCP client that can send an Authorization header works. The two most common ones:

Claude Code

claude mcp add --transport http postfach https://mail.example.org/mcp \
  -H "Authorization: Bearer <token>" --scope user

claude.ai custom connector (web and mobile apps)

claude.ai can talk to this server as a custom connector, which also makes it available in the Claude mobile apps — the connector is configured once and appears there automatically.

Custom connectors normally require OAuth, which this server does not offer. What it relies on instead is the request-header option in the add-connector dialog (authentication "None" plus a static header). At the time of writing Anthropic describes that option as available to a limited set of organizations, so it may not appear for your account — check the dialog before planning around it.

Configuration, and the three pitfalls that cost the author an afternoon:

• URL: your public https://…/mcp endpoint. Authentication: None. Add a request header Authorization with the value Bearer <token> — including the scheme and the space; the value is sent verbatim, so a bare token produces nothing but 401s.

• A connector's authentication settings cannot be changed later. To rotate a token, delete the connector and create it again. This pairs well with EXTRA_TOKENS: give the connector its own token and it can be revoked without touching your other clients.

• The connection test in the dialog can fail even when everything is configured correctly (some of its probes are sent without the header). If the server logs show 401s from the dialog but your header is right, deleting and re-creating the connector is faster than debugging.

One consequence for your network setup: connector traffic originates from Anthropic's backend, not from your browser — the server must be reachable from the public internet, a VPN or tailnet is not enough for this path. To keep the exposed surface small you can restrict it to Anthropic's published egress IP range at your proxy or firewall; the bearer token remains the actual authentication either way.

Security model

• No send, no delete. The server cannot transmit mail or destroy it; those tools do not exist at runtime. Drafts are filed via IMAP APPEND into your drafts folder and stay there until you act on them.

• Mail content is untrusted. Bodies and headers are returned in structured fields, never interpreted; tool descriptions warn the model that message content is third-party input. Header fields of drafts are validated against CRLF injection.

• Bearer token on every MCP request (constant-time comparison), minimum 32 characters. The health endpoint is the only unauthenticated route.

• Host header allowlist (ALLOWED_HOSTS) rejects requests addressed under any other name — DNS-rebinding protection. Behind a proxy or tunnel you must add the public host name, or every request fails with 421.

• Transport security is your job. The server speaks plain HTTP and binds to localhost by default; put a TLS-terminating reverse proxy, tunnel, or VPN in front of it. Do not expose the port directly.

• Errors are terse. IMAP failures reach the client as one English sentence; credentials and tracebacks never do.

Limitations

• One account per server instance.

• Drafts carry no formatting beyond line and paragraph breaks, and IMAP cannot edit them in place — a changed draft means a new one.

• Some clients render plain-text drafts through an HTML composer and lose all line breaks (observed in Spark on macOS and Android; webmail shows the same draft correctly). DRAFT_FORMAT=html works around this by adding an HTML alternative part.

• Attachments are reported as metadata only (name, type, size); their content is not retrievable.

• Message bodies are capped at 50,000 characters, list/search results at 100 messages per call, list_headers at 500 headers per page; drafts at 500,000 characters.

• Lossless export of raw messages is out of scope — for backups, use a dedicated tool such as mbsync or offlineimap.

• HTML-only messages are converted to text with a deliberately simple converter — layout is lost, links are kept visible.

• mark_read, mark_flagged and move_messages trigger an expunge in the source folder (imap-tools behavior; a move is IMAP-internally copy + delete + expunge). Harmless for this server, which never sets the deleted flag itself, but it also purges messages other clients have marked deleted in that folder.

Development

python -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest
.venv/bin/python -m ruff check . && .venv/bin/python -m mypy

Tests run entirely without network access — enforced by the test suite itself, which fails any accidental socket connect.

License

MIT

Built with assistance from Claude Code.