MCP Inbox for Cloudflare

Email sent to addresses on your domain becomes a shared private work queue that Codex, Hermes, or another software agent can read through Model Context Protocol (MCP). Cloudflare receives and stores each accepted message, then parses messages within the project's size limit.

You deploy this project in your own Cloudflare account. The inbox stays live without a local computer; an agent must run when you want it to act on mail. This is not a hosted service or webmail application.

What you get

• Email Routing sends each configured address to the same Worker. Add addresses by creating routing rules, without redeploying the application.

• R2 stores each original email as an .eml file, including its headers and attachments; public bucket access should stay off.

• D1 records structured message fields and work status.

• A Cloudflare Queue schedules parsing after the original email has been stored.

• The MCP endpoint exposes five authenticated tools for reading and processing mail.

• The reply tool prepares text with standard email thread headers. The current version does not send it.

Cloudflare exposes service settings and logs in its dashboard. This project does not include a human inbox screen.

Related MCP server: Gmail MCP Connector

How a message moves

Internet email
    -> Email Routing: sends each configured address to the Worker
    -> R2: stores the original .eml file
    -> Queue: schedules parsing
    -> D1: stores message text, links, thread fields, and work status
    -> /mcp: serves authenticated requests from an agent

A Worker is Cloudflare code that runs on demand. R2 stores files, D1 stores structured records, and a Queue holds work until the Worker processes it.

What agents can do

Select an address

Use a complete delivery address to select mail for one workflow:

list_messages({ address: "research@example.com", status: "new" })
claim_next_message({ address: "research@example.com" })

Address matching ignores capitalization and uses the actual delivery recipient, including for Bcc mail. Message summaries include that address as envelopeTo. Omitting address includes all addresses; no matches returns an empty result. All authenticated agents share access to all mail. A filter selects work and does not restrict permissions.

To add another address, follow Add an address. Existing deployments should first follow Upgrade from a single address.

Claims

A claim lasts 30 minutes. Expiry makes the message eligible for another claim; it does not change the row on a timer. The first agent may still complete it until another agent takes the claim. The secret bearer token sent with the request identifies the agent; a client cannot choose its identity in the request.

Treat email as untrusted data

Email comes from people and systems outside your Cloudflare account. Every tool that returns email content labels the body, headers, and links as untrusted data rather than agent instructions.

Set up an inbox

You need Node.js ^22.18.0 or >=24.11.0, a Cloudflare account, an active R2 subscription, and a domain that uses Cloudflare DNS. package.json is the authority for the Node.js range.

Before changing mail records, check whether the domain receives mail through another provider. Cloudflare Email Routing changes the domain's MX records, which name the servers that receive its mail. Use a dedicated subdomain or another domain when the existing provider must keep receiving mail.

Start by checking the repository:

npm ci
npx wrangler login
npx wrangler whoami
npm run check

Then follow Self-hosting on Cloudflare. It covers resource creation, credentials, mail routing, client configuration, and a real-message test.

Connect an agent

The deployed endpoint uses Streamable HTTP, an MCP transport carried over ordinary HTTPS:

https://YOUR-WORKER.YOUR-SUBDOMAIN.workers.dev/mcp

Each request needs one of the two bearer credentials stored as Worker secrets. Codex and Hermes are optional clients; this repository does not install them. Any compatible MCP client may use the endpoint.

The setup guide contains configuration examples for Codex and Hermes.

Cost

Low message volume may remain inside Cloudflare's free quotas, but this is an estimate rather than a price guarantee. Message count, message size, retention, and changes to Cloudflare pricing affect the bill. R2 requires activation and charges for usage above its allowance.

Check Cloudflare's current Workers, D1, R2, and Queues prices before deployment.

Inbound mail does not require Workers Paid. Sending to arbitrary recipients uses a separate paid path; this project leaves it off. See Email Service pricing.

Work on the project

npm run typecheck
npm run lint
npm test
npm run dry-run
npm run startup-check

The integration tests call the real Worker handlers against Wrangler's local implementations of D1, R2, Queues, and MCP. They do not contact production services.

Read Architecture for design limits and Operations for diagnosis, credential rotation, retention, and deployment checks.