cloudflare-agent-inbox
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
cloudflare-agent-inbox
Experimental software. This project is early, was built for its author's own use, and has had little real-world use. It has been checked against only one mail provider's real forwarding behaviour (iCloud Mail). Expect rough edges and breaking changes, and no stability or support guarantees. It handles untrusted email on behalf of AI agents: before pointing an agent at real mail, read docs/security.md, and give the agent only capabilities you would be comfortable with an attacker steering. Use it at your own risk.
A Cloudflare Worker that files forwarded emails into lanes, which AI agents read through a narrow, mostly read-only MCP server. A separate admin CLI manages lanes, agent tokens and secrets.
Unofficial. This project is not affiliated with, endorsed by, or sponsored by Cloudflare. It runs on Cloudflare's developer platform and uses the name descriptively.
You forward chosen emails (receipts, invoices, notifications) from your own mailbox to a lane's unguessable address. The Worker checks that the mail really came from you, turns it into clean plain text, stores the original, and makes it available to the agents you granted that lane, and nobody else.
How it works
forwarded mail ─► Email Routing ─► email() handler
1. address token → lane unknown → drop silently
2. sender + DKIM checks fail → drop silently
3. lane paused verified sender → bounce (so you notice)
4. size and attachment policy fail → drop silently
(every rejection is logged headers-only, capped per day)
5. clean text → D1; raw message and attachments → R2
6. the lane's attachment transforms (e.g. unzip)
fetch() handler
MCP host /mcp/agent bearer tokens, scoped to granted lanes
share host /s/<token> short-lived download links
scheduled() ─► retention purge, expired links, old rejections
agent-inbox CLI (your machine) ─► Cloudflare API: D1 and Workers secrets
(there is no admin route on the Worker)Lanes are the unit of policy. Each has its own address, allowed senders, attachment rules, transforms, size and retention limits.
Sender checks accept mail you compose or forward by hand (DKIM for your domain) and, per lane, mail your provider forwards by a server-side rule (the provider's ARC record of the original sender). See docs/security.md.
Addresses look like
inbox+<token>@<mail hostname>. The token is 160 random bits. Email Routing needs a single literal rule forinbox@<mail hostname>, with subaddressing enabled.No AI in the pipeline. Conversion to text is deterministic: HTML is converted to text (removal of hidden text is best effort: it catches common tricks, not every one), zero-width and bidi characters are removed, text is NFKC-normalised, links become
text (domain).Agents get a bearer token and four tools:
list_messages,get_message,create_share_linkandmark_processed. Body text and other third-party fields come back under names startinguntrusted.
New here? Follow docs/getting-started.md, or paste the agent-guided setup prompt into an agent.
See docs/security.md for the threat model, docs/operations.md for logs and diagnosing problems, docs/lanes.md for lane recipes and docs/deploy.md for deployment.
Related MCP server: packet-pigeon
Quick start
npx npm@11 install
export AGENT_INBOX_CLI_API_TOKEN=... # narrow: Workers Editor and D1 Edit only
export CLOUDFLARE_ACCOUNT_ID=...
export AGENT_INBOX_WORKER_NAME=... # also the D1 database name
export AGENT_INBOX_MAIL_HOSTNAME=mail.example.com
npm run cli -- lanes create receipts --description "Shop receipts"
npm run cli -- agents create my-agent # interactive terminals only; prints the token once
npm run cli -- agents grant my-agent receipts
npm run cli -- messages inject-test receipts --text "Total 3.50 GBP"lanes create prints the lane's address; point your mail rule at it.
CLI
npm run cli -- <command>. Output is human-readable, or JSON with --json.
It prints metadata only; message bodies need messages get <id> --show-body.
Command | Does |
| manage lanes and their addresses |
| manage agent tokens and what they can read |
| set a Worker secret; the value is read from the terminal or stdin |
| inspect and fix messages |
| see what was rejected, and why |
Destructive commands (lanes delete, lanes rotate, agents revoke,
messages delete) ask for confirmation, or refuse in a non-interactive
session unless --yes is passed. Automation should not pass --yes.
agents create refuses to run unless it has a terminal, so a token is never
captured by a tool or transcript.
Configuration
Deployment values (hostnames, allowed senders, DKIM domains) are never
committed. wrangler.example.jsonc is a template; the real config is rendered at
deploy time from environment variables (see .env.example). You deploy with
npm run deploy from a clone, with no fork needed; Workers Builds is an optional
alternative. See docs/deploy.md.
Examples in this repository use example.com and made-up senders only.
Threat model (summary)
Email bodies are untrusted data written by third parties. This project keeps risk down with tight ingress control, per-lane scoping and a minimal agent surface, not by filtering content. Safety therefore also depends on what the consuming agent is allowed to do: give an agent that reads email only the capabilities you would be comfortable with an attacker steering.
Development
npx npm@11 install # npm 10 can hit a peer-dependency bug with Vitest
npm test # Vitest inside the Workers runtime
npm run typecheck
git config core.hooksPath .githooks # enable the pre-commit scansThe pre-commit hook scans for personal values using a denylist you keep
outside the repository (.pii-denylist, which is git-ignored, or
~/.config/agent-inbox/denylist.txt; one term per line). npm run pii-scan -- --history scans every commit. CI runs
gitleaks on every push.
Licence
MIT. See LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Email inboxes for AI agents: send, receive, reply, search, and manage threaded email over MCP.
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Hosted email for AI agents: create inboxes, send, receive, and reply over MCP with scoped API keys
Your agent needs a mailbox of its own — to receive, thread, draft and send, with attachments, without borrowing your personal inbox or your company's SMTP. **What you can ask for** • "Create an inbox for this agent and tell me its address." • "Read the new messages in this thread and draft a reply." • "Send this message with the attachment and wait for the response." • "Search this inbox for everything from that domain." • "Show delivery metrics and the events on this inbox." **How to use it** Point any MCP client at https://mcp.aisa.one/mail/mcp and sign in with OAuth — there is no key to create or paste. 49 tools: create and delete inboxes, list and read messages, raw message bodies, attachments, threads, drafts and draft attachments, send and reply, message search, inbox events, metrics, and list entries — reads and writes. **Why this rather than the source** A real inbox an agent owns, rather than an SMTP credential it borrows from a human. **It is also a door to the rest** The same login reaches 26 sources and 580+ operations. Find the contact elsewhere in the catalogue, then write to them from here — without adding a second server. **What it costs** Finding and inspecting an operation is free. Running one is billed per call at API prices, with no seat and no monthly minimum, and every call takes max_price_usd so an agent cannot overspend by accident. **Where else it reaches** https://mcp.aisa.one/sales/mcp finds the person to write to.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables MCP-compatible AI assistants to securely search multiple mailboxes, reconstruct email threads, and inspect attachments through read-only tools without altering mailbox state.Apache 2.0
- FlicenseNot gradedqualityCmaintenanceEmail capabilities for AI agents to receive, read, reply, and send through MCP.-
- AlicenseNot gradedqualityBmaintenanceEnables users to browse folders, list and search messages, read emails, and retrieve selected attachments through a private read-only MCP bridge with OAuth and safe HTML extraction.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients and AI assistants to search and read email through read-only IMAP access, including bounded message reads and explicitly selected attachment retrieval.MIT