Skip to main content
Glama
cloudflare-agent-inbox

cloudflare-agent-inbox

by lukeredpath

cloudflare-agent-inbox

WARNING

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 for inbox@<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_link and mark_processed. Body text and other third-party fields come back under names starting untrusted.

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

lanes create|list|get|update|pause|resume|delete|rotate

manage lanes and their addresses

agents create|list|grant|ungrant|revoke

manage agent tokens and what they can read

secrets set LANE_SECRET_NAME

set a Worker secret; the value is read from the terminal or stdin

messages list|get|mark-unprocessed|keep|delete|inject-test

inspect and fix messages

rejections list

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 scans

The 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…

    Related MCP Connectors

    • Email inboxes for AI agents: send, receive, reply, search, and manage threaded email over MCP.

      https://mcp.agentmail.to/mcp
    • Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.

      https://www.primitive.dev/mcp
    • Hosted email for AI agents: create inboxes, send, receive, and reply over MCP with scoped API keys

      https://api.agenticemail.dev/mcp
    • 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

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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