benethos-mailbox-mcp

mailbox-mcp

Beta, version 0.5.0. Usable with real accounts. A breaking change of the API or the configuration is announced in the changelog. Stored data is carried forward by migrations.

The MCP server of Mailbox, on PyPI as benethos-mailbox-mcp. It gives Claude and other AI assistants your mailboxes, as far as its token allows. It searches and reads mail, tells what is new since it last looked, looks at attachments (PDF pages as images), sorts messages, writes drafts and, if you let it, sends.

It reaches mail only through the REST API of mailbox-service, which has to be running, with the Python client mailbox-client. It holds no mail password and no mail library. The rights of the user whose token it carries decide what it may do. It runs in one of two ways. Over stdio, the MCP client starts it, and it ends with the client. Over streamable HTTP, it runs as a server of its own.

What the project is for: the repository's README.

Contents

• Claude Desktop extension
• Install
• A token for it
• Claude Desktop without the extension
• Claude Code
• Without a client
• Options
• Over HTTP
• Log and timeouts
• Container
  • With docker run
  • Beside a service in operation
• Tools

Claude Desktop extension

The easiest way for Claude Desktop. Nothing else has to be installed. Claude Desktop sets up the server with uv and Python of its own.

Before you start you need:

• mailbox-service running and reachable from this machine, with your accounts connected
• a token of a user with the rights the server should have, see A token for it.

Then:

• Download benethos-mailbox-mcp.mcpb from the latest release.

• Open the file with Claude Desktop, with a double click or in Claude Desktop under Settings, Extensions. It shows the extension as Mailbox. Install it.

• Fill in its settings:

  Field	What goes in
  Token	The token. Required.
  Address of the service	Where the service runs. Keep http://127.0.0.1:8080 when it runs on this machine with its defaults. Otherwise its address, such as https://mail.example.org.
  Plain http to another machine	Leave it off. Turn it on only for a service on another machine that has no https, such as one in a test machine of your own. The token then travels unencrypted. On this machine it is not needed.

• Make sure the extension is enabled and start a new chat. Ask, for example, which mail accounts it can see. The answer lists the accounts the token has rights on.

Each release carries the extension twice: as benethos-mailbox-mcp.mcpb, the link above, which always leads to the latest, and as benethos-mailbox-mcp-<version>.mcpb. An extension runs the version of the server it was made with. To update, download the newer file and open it the same way.

Install

For Claude Desktop see Claude Desktop extension. For other clients there is nothing to install either. An MCP client starts it over stdio with uv's uvx benethos-mailbox-mcp (see below). To have the command at hand:

uv tool install benethos-mailbox-mcp      # or: pipx install benethos-mailbox-mcp
benethos-mailbox-mcp --version

From a clone of the repository: uv run --directory <path to the clone> benethos-mailbox-mcp. The path is the folder with pyproject.toml and uv.lock at its top.

The container image is ghcr.io/benethos-hub/benethos-mailbox-mcp. See Container.

The server is listed in the official MCP Registry as io.github.benethos-hub/benethos-mailbox-mcp, with the PyPI package and the Claude Desktop extension. An MCP client that reads the registry finds it there.

A token for it

The MCP server acts as one user of the service and can do exactly what that user may. Give it a user of its own with only the rights it needs. In the UI, at http://127.0.0.1:8080/ui, signed in as an administrator:

• Users, New user. Give it a name, such as claude-desktop, and leave Signs in to at "the API only, with tokens".
• Under Grants, tick the accounts it may use and its Rights, such as mail.read. Leave the Service rights empty.
• Create. The new user's page opens.
• On its tab Access, under Tokens, New token. Say what it is for, such as laptop. Days valid left empty means it does not expire. Create token.
• Copy the token the page shows. It is shown this once.

Over the API, this example lets it read two accounts:

curl -X POST http://127.0.0.1:8080/v1/users \
  -H "Authorization: Bearer <admin token>" -H "Content-Type: application/json" \
  -d '{"name": "Claude", "grants": [{"accounts": ["acc_…", "acc_…"], "allow": ["mail.read"]}]}'
curl -X POST http://127.0.0.1:8080/v1/users/<user id>/tokens \
  -H "Authorization: Bearer <admin token>" -H "Content-Type: application/json" \
  -d '{"name": "claude-desktop"}'

The second answer holds the token. It is shown this once. The account ids come from GET /v1/accounts.

Rights that matter here: mail.read to read and to ask what is new, mail.write to sort and file, drafts to write drafts, send to send, mail.share beside mail.read to hand an attachment to another service. A grant can limit sending to certain recipients and a number per day (Send only to and Sends per day in the UI).

The server needs no accounts.read. It learns its accounts from /v1/me, which every token may call. That answer names each account the token has any right on, and what it may do there. accounts.read would add the full account records with the server settings, which the model does not need.

Claude Desktop without the extension

In claude_desktop_config.json (Settings, Developer, Edit Config):

{
  "mcpServers": {
    "mailbox": {
      "command": "uvx",
      "args": ["benethos-mailbox-mcp"],
      "env": {
        "MAILBOX_SERVICE_URL": "http://127.0.0.1:8080",
        "MAILBOX_SERVICE_TOKEN": "<token>"
      }
    }
  }
}

From a clone instead: "command": "uv" and "args": ["run", "--directory", "<path to the clone>", "benethos-mailbox-mcp"]. On Windows write the path with \\ or /. Restart Claude Desktop after a change.

Claude Code

claude mcp add mailbox \
  -e MAILBOX_SERVICE_URL=http://127.0.0.1:8080 \
  -e MAILBOX_SERVICE_TOKEN=<token> \
  -- uvx benethos-mailbox-mcp

Add -s user to have it in every project. claude mcp list shows whether it connects.

Without a client

MAILBOX_SERVICE_URL=http://127.0.0.1:8080 MAILBOX_SERVICE_TOKEN=<token> benethos-mailbox-mcp

Options

Option	Environment	Default
–	MAILBOX_SERVICE_URL	http://127.0.0.1:8080, where the service answers
–	MAILBOX_SERVICE_TOKEN	none and required, the token of the user it acts as
–	MAILBOX_SERVICE_ALLOW_HTTP	off. 1 allows http to a host other than this machine
--transport	MAILBOX_MCP_TRANSPORT	stdio, or streamable-http
--host	MAILBOX_MCP_HOST	127.0.0.1
--port	MAILBOX_MCP_PORT	8000
--path	MAILBOX_MCP_PATH	/mcp
--allowed-hosts	MAILBOX_MCP_ALLOWED_HOSTS	none, comma-separated Host values
--allowed-origins	MAILBOX_MCP_ALLOWED_ORIGINS	none, comma-separated
--log-level	MAILBOX_MCP_LOG_LEVEL	INFO
–	MAILBOX_MCP_RIGHTS_SECONDS	60, how often it asks what its token may do. 0 asks only at start
–	MAILBOX_MCP_BEARER_TOKEN	none, what HTTP clients must send
--env-file	MAILBOX_MCP_ENV_FILE	a settings file, see below

The command line wins over the environment, the environment over a settings file. An MCP client usually passes the settings in its own configuration. Without a client, or for a server over HTTP, they can go into a .env file. The first that exists is read: the file named with --env-file or MAILBOX_MCP_ENV_FILE, which must exist, then config/benethos-mailbox-mcp/.env in the working directory, then .env in the settings folder of the operating system: %LOCALAPPDATA%\benethos-mailbox-mcp\config on Windows, ~/.config/benethos-mailbox-mcp on Linux, ~/Library/Application Support/benethos-mailbox-mcp/config on macOS. It is read for MAILBOX_MCP_* and MAILBOX_SERVICE_* alone. A wrong value stops the start and names the setting. The file holds the API token, so keep it readable by its owner alone. Template: config/benethos-mailbox-mcp/.env.example.

MAILBOX_SERVICE_URL takes https anywhere and http to this machine only (localhost or a loopback address such as 127.0.0.1 or ::1), since the token goes with every request. For http to another host, e.g. a container beside it, set MAILBOX_SERVICE_ALLOW_HTTP=1. Without it the server does not start.

Over HTTP

MAILBOX_SERVICE_URL=http://127.0.0.1:8080 MAILBOX_SERVICE_TOKEN=<token> \
MAILBOX_MCP_BEARER_TOKEN=<a long random token> \
  benethos-mailbox-mcp --transport streamable-http

The server answers at http://127.0.0.1:8000/mcp. For Claude Code:

claude mcp add --transport http mailbox http://127.0.0.1:8000/mcp \
  --header "Authorization: Bearer <bearer token>"

• Bearer token. With MAILBOX_MCP_BEARER_TOKEN set, every HTTP request must carry Authorization: Bearer <token>. Anything else gets 401. It has no command-line option, since arguments show in the process list. Without it the server logs a warning and admits anyone who can reach the port. Over stdio the token is ignored.
• Two tokens. The bearer token only admits MCP clients. The server calls the REST API with its own MAILBOX_SERVICE_TOKEN, and that user's rights decide which tools exist, for every client alike.
• Host check. Against DNS rebinding the server checks the Host and Origin headers. On a loopback bind it admits 127.0.0.1, localhost and [::1]. With --allowed-hosts it admits exactly those, and --allowed-origins alone admits the hosts of those origins. A bind such as 0.0.0.0 without a list checks nothing, so set the list there. A refused host gets 421, a refused origin 403.
• Beyond your own machine, put a TLS reverse proxy in front.

Log and timeouts

The server writes its log to stderr only, since over stdio stdout carries the MCP messages. An MCP client keeps that log in its own files. Each line has the time, the level, where it comes from and the message, written as the service writes its own: in colour on a terminal unless NO_COLOR is set, plain elsewhere, its tokens masked as ***. At start it names the settings file it read, the transport, the service's address and the tools it serves, and warns where its token may read mail and send it to any address. Over HTTP without MAILBOX_MCP_BEARER_TOKEN it warns as well. A tool that fails writes a warning with the tool's name and the error's code, never its arguments. httpx, httpcore and the MCP library write from warning on, since a request's URL carries search terms and message ids.

Towards the service it waits 5 seconds for a connection, 30 seconds for an answer and 120 seconds for an attachment, which may be large. Past that the model reads that the service is not reachable, or that it did not answer in time and a narrower request may help.

Container

The image ghcr.io/benethos-hub/benethos-mailbox-mcp serves over streamable HTTP on port 8000, as an unprivileged user, and the command below runs it on a read-only root file system. A client that starts the server over stdio needs no image. Tags: the version (0.5.0), the minor version (0.5) and latest.

With docker run

Next to a service container named mailbox-service (see the service's README), in a network both share:

docker network create mailbox
docker network connect mailbox mailbox-service

docker run -d --name mailbox-mcp --restart unless-stopped --network mailbox \
  -p 127.0.0.1:8000:8000 --read-only --tmpfs /tmp \
  -e MAILBOX_SERVICE_URL=http://mailbox-service:8080 \
  -e MAILBOX_SERVICE_ALLOW_HTTP=1 \
  -e MAILBOX_SERVICE_TOKEN=<token> \
  -e MAILBOX_MCP_BEARER_TOKEN=<a long random token> \
  -e MAILBOX_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000 \
  ghcr.io/benethos-hub/benethos-mailbox-mcp:0.5.0

Inside the container the server binds to 0.0.0.0. So MAILBOX_MCP_ALLOWED_HOSTS names the Host values clients use: the port as published on the host, or the host name behind a proxy.

Beside a service in operation

containers/production/ runs the service. The MCP server acts as one user, with that user's token, so each client has one of its own. Usually the client starts it over stdio as above, with MAILBOX_SERVICE_URL set to the service's address, for example https://<MAILBOX_DOMAIN> behind its Caddy. For a client that connects over HTTP, instances of this image run beside the service with the profile mcp, one per token, from the template mcp.yaml. Caddy can route to each under a path of its own, such as https://<MAILBOX_DOMAIN>/mcp/agent. Its README has the steps, also for an instance on another host. For development, containers/development/compose.yaml starts it beside a service built from the repository, with the profile mcp.

Tools

At start the server asks /v1/me what its token may do and offers only the tools that fit. While it runs it asks again every MAILBOX_MCP_RIGHTS_SECONDS, and when a tool is refused for a missing right, and tells its client when the tools change (notifications/tools/list_changed), so a right granted or taken away in the service shows without a restart. Claude Desktop lists the tools anew when told. When the service refuses the token, every tool goes away and the server asks no more, since each refusal counts against the address like a wrong token. A new token then needs a restart. A user that may do nothing keeps list_accounts alone, which lists no account. The tools:

Tool	Needs	What it does
list_accounts	–	the accounts, their addresses, what may be done on each, the limits on sending, a warning where the token may read and send anywhere, what an account cannot do, such as a POP3 mailbox without folders, and an account that needs a person, such as a new sign-in
list_folders	mail.read	folders with id, name, role, parent and counts
search_messages	mail.read	find mail by text, sender, recipient, subject, days, flags, attachments, in one account or all, in the inbox or a folder, or with all in every folder but the trash and junk
get_message	mail.read	one mail as plain text, cut to max_chars, 4,000 by default, with its folders, its marks in words, its keywords, and for a draft the mail it answers
get_thread	mail.read	a conversation in every folder, oldest first, from a mail of it such as a search hit or from its thread id: the newest 20 mails as plain text, sharing max_chars, 12,000 by default
get_attachment	mail.read	an attachment: images up to 5 MiB as images, PDF pages as PNG images (first_page, pages, up to 10, 4 megapixels a page and 12 together), text as text, HTML as the text a reader sees, both cut to max_chars, 20,000 by default. Other types and larger images by name only. An image, PDF or text above 10 MiB is refused, and a PDF whose pages take longer than 30 seconds to render.
share_attachment	mail.share	a link to an attachment for another service, which fetches the file itself without it passing through the model: a URL that service fetches once, without a token, until it ends, after the service's MAILBOX_SERVICE_LINK_SECONDS, 120 by default, with when it ends, the type, the size and the file name
whats_new	mail.read	mail created, updated or deleted since the state of an earlier call, ids only, in one account or all
update_messages	mail.write	up to 100 mails of one account: read or unread, star, move (folder id or role such as archive), add and take off keywords, add and take off labels where a mail can be in several folders at once, or into the trash
create_folder	mail.write	a new folder, at the top or in a parent (id or role)
update_folder	mail.write	renames a folder, or moves it into another one or to the top. Deleting a folder is not a tool
list_drafts	drafts	the drafts of an account
create_draft	drafts	a draft in plain text or HTML, recipients optional. With original_id a reply, reply to all or forward, with quote false without the original, forward_as attachment for the original as a file. reply_to, attachments as base64, attach_from for attachments of other mail.
update_draft	drafts	replaces a draft as a whole, keep_attachments keeps stored files. It answers with the draft's id from now on, a new one at Microsoft, JMAP and Gmail
delete_draft	drafts	deletes a draft for good, reaches drafts only
send_message	send	sends a mail at once, plain text or HTML. It takes what create_draft takes.
send_draft	send	sends a stored draft

Each tool has a title for display and the standard MCP hints. Clients can use them to decide when to ask the person before a call.

• Read-only: the tools that only read. share_attachment is not among them: it makes a link that hands mail out.
• Destructive: update_messages, update_folder, update_draft, delete_draft and both send tools. They can move mail to the trash, rename a folder, overwrite or delete a draft, or send mail.
• Idempotent: update_messages, update_folder, update_draft and delete_draft. The same call again changes nothing more. The send tools are not marked idempotent, although a repeat within 24 hours sends nothing.
• Open world: every tool except list_accounts, since they reach mail from and to anyone.

share_attachment is for a file another service takes over, such as another MCP server the client runs beside this one. The model carries only the URL across. That service fetches the bytes from the Mailbox service directly, with a plain GET and no token of the Mailbox service. The link holds once and for as long as the service is set to, MAILBOX_SERVICE_LINK_SECONDS. Its rights are those of this server's token: when the link is used, the token must still hold get_attachment and share_attachment on the mail. mail.share is in no role template, so a grant names it on purpose. Whoever holds the URL gets the file, so the model hands it to that service alone, never to the sender of the mail or anyone else.

Each send carries an Idempotency-Key derived from the call. The same call repeated within 24 hours sends nothing and returns the first result. Give a user send only if the model may send without a person looking at the mail first. With drafts alone it writes drafts for a person to send.

Mail content comes back inside <mail-content> markers, the headers and attachment names as much as the body. Strangers wrote it, so it is data, not instructions. A list of messages, which is JSON, carries a note saying the same of from and subject, a list of drafts of to and subject, which a reply takes from the mail it answers. HTML is turned into text without its hidden parts: text not shown, too small or faint to read, pushed off the page or in the colour of its own background.