MCPEmails

Give your AI agent an inbox. A hosted Model Context Protocol server that lets Claude, Cursor, or any MCP‑compatible client read, search, send, organize, and schedule email through your existing mailboxes — without ever storing your mail.

Connect a mailbox once, paste one URL into your agent, and it can work your inbox live. Email is fetched on demand and never retained; credentials are encrypted at rest and decrypted only at call time inside an isolated edge function.

🔗 mcpemails.com · 📚 Docs · 💳 Pricing

---

Contents

• How it works
• Quick start (connecting an agent)
• Capabilities
• Tools
• OAuth scopes
• Supported providers
• Pricing
• Architecture
• Repository layout
• Local development
• Environment variables
• Database & migrations
• Deployment
• Self-hosting
• Internationalization
• Security model

---

How it works

1. Connect a mailbox. Sign in at mcpemails.com and connect Outlook / Microsoft 365 (Sign in with Microsoft, over Microsoft Graph), Gmail (a Google app password over IMAP by default, or Sign in with Google), or any IMAP/SMTP account (app password). Credentials are encrypted with AES‑256‑GCM before they touch the database.
2. Get access. OAuth‑capable clients (claude.ai, Claude Desktop, Cursor) connect in one click via OAuth 2.0 + PKCE. Everything else uses a scoped API key (mcpe_…).
3. Point your client at the server. The MCP endpoint is a single URL:

   https://mcpemails.com/api/mcp
   

4. Your agent works the inbox. It calls tools like inbox_list, email_read (action: "search"), email_compose (action: "send"), and schedule (action: "create"). Each request fetches live from your provider — nothing is mirrored or cached server‑side.

Permissions are scoped per key, so you can hand an agent read:email only, or grant it send and folder management without ever exposing delete.

Quick start (connecting an agent)

Claude Desktop / Cursor (OAuth): add a remote MCP server pointing at https://mcpemails.com/api/mcp and approve the consent screen. Pick the scopes the agent should have.

API key (any MCP client): create a key in the dashboard, choose its scopes and (optionally) restrict it to specific inboxes, then send it as a bearer token:

// Example MCP client config
{
  "mcpServers": {
    "mcpemails": {
      "url": "https://mcpemails.com/api/mcp",
      "headers": { "Authorization": "Bearer mcpe_your_key_here" }
    }
  }
}

The protocol is JSON‑RPC 2.0 over HTTP (MCP 2025-06-18, Streamable transport). Start every session with inbox_list — it returns the inboxes the key can reach, their per‑provider capabilities, and a versioned compatibility profile. The profile marks normalized operations as exact, different, or unavailable, so agents can preserve provider differences rather than silently weakening a request.

Setup guides

Copy‑paste instructions per client, including where each one keeps its config file: mcpemails.com/docs/clients.

Claude · Claude Code · ChatGPT · Cursor · VS Code · Cline · Windsurf · Gemini CLI · Zed · JetBrains · Raycast · Warp · curl

Capabilities

• Live, never stored — email is read straight from your provider on each call; no message bodies are persisted.
• Multi‑provider — Outlook / Microsoft 365 via Microsoft Graph (Sign in with Microsoft), Gmail via a Google app password or Sign in with Google, plus any IMAP/SMTP mailbox (Fastmail, iCloud, Yahoo, Zoho, Yandex, self‑hosted…) via app password.
• No relay — outbound mail is sent through your provider's SMTP/API, from your real address.
• Granular scopes — eight permission scopes, grantable independently per API key and per inbox.
• Batch & search‑and‑act — read, move, delete, or flag up to hundreds of messages in one call, including "search then move/delete" combinators.
• Drafts & scheduling — compose drafts and queue messages for future send (server‑side dispatch).
• Provider‑agnostic search — Gmail syntax, Microsoft Graph KQL and IMAP SEARCH are normalized behind one email_read (action: "search") interface.
• Team‑ready: workspaces, members, roles, SSO, and an audit log on the Team plan.

Tools

17 tools you call directly. Most are resource-oriented and take an action argument that selects the specific operation (and, for actions that need different privileges, the required scope):

• inbox_list - Lists the inboxes the key can reach, with each one's provider capabilities.
• email_read - Lists, reads and searches messages, in batches, plus attachments, extracted attachment text and the original .eml.
• email_organize - Moves, copies, flags and archives messages you name by id, singly or in batches.
• email_search_and_move - Moves every message matching a search into a folder. Its own tool, and the destructive one, because a wrong filter relocates a whole inbox.
• email_delete - Trashes or permanently deletes messages, singly, in batches, or by search.
• email_compose - Sends, replies and forwards through your own provider, from your real address.
• folder_list - Lists folders (labels on Gmail) with their provider-native IDs and message counts. Read-only.
• folder - Creates, renames and deletes folders (labels on Gmail).
• draft_list - Lists the drafts saved in the inbox, with their draft ids. Read-only.
• draft - Creates, updates, sends and deletes drafts, including provider-native replies.
• schedule_list - Lists what is queued for future delivery. Read-only.
• schedule - Queues a message for future delivery, and cancels one that is queued.
• signature_get - Reads the signature and sender name configured for an inbox. Read-only.
• signature_set - Sets the signature appended to outbound mail, and the sender name.
• automation_read - Lists triage rules, reads one, shows run history, and dry-runs a filter. Read-only.
• automation - Creates, updates, enables, disables and deletes unattended triage rules, with no model in the loop.
• contact_search - Looks up contacts by scanning recent mail live, with no stored address book.

| Tool | Actions | Scope(s) | | --- | --- | --- | | inbox_list | (single action) | read:email | | email_read | list, read, read_batch, search, attachment, extract, original | read:email (search also accepts search:email) | | email_organize | move, move_batch, copy, copy_batch, flag, archive | manage:folders | | email_search_and_move | (single action) | manage:folders | | email_delete | delete, delete_batch, search_and_delete | delete:email | | email_compose | send, reply, forward | send:email | | folder_list | (single action) | read:email | | folder | create, rename, delete | manage:folders | | draft_list | (single action) | manage:drafts | | draft | create, reply, update, send, delete | manage:drafts (create/reply/update/delete), read:email (reply also), send:email (send) | | schedule_list | (single action) | schedule:email | | schedule | create, cancel | schedule:email | | signature_get | (single action) | read:email | | signature_set | (single action) | send:email | | automation_read | list, get, runs, preview | manage:automations | | automation | create, update, enable, disable, delete | manage:automations | | contact_search | (single action) | manage:contacts (also accepts read:email) |

A full-scope key sees 22 tools in tools/list: the 16 above plus six app-only tools (approval_review, approval_decide, approval_update, approval_schedule, bulk_execute, bulk_cancel). Those carry _meta.ui.visibility: ["app"] and drive the review card an MCP client renders for a held send or a previewed bulk operation, rather than being composed by hand.

Notes:

• Tools accept either an explicit inbox_id (UUID) or an inbox email address; single‑inbox keys auto‑resolve the target.
• Batch actions cap at 50 (email_read's read_batch) to 500 (move/delete/flag) messages per call.
• For a targeted mutation, first use email_read with action: "search", then pass the returned message_id or message_ids to email_organize or email_delete. Search fields are accepted only by email_search_and_move and email_delete's search_and_delete action.
• contact_search scans recent mail live, so there is no stored address book.
• email_read's original action returns one complete provider-stored MIME message as a portable .eml file (up to 25 MB). It is read-only and never marks the message as read.
• draft's send action requires send:email, not manage:drafts, so a key that can only manage drafts can't use them to bypass the send‑mail consent.
• draft's reply action creates an unsent, provider-native reply in the source conversation. It needs both manage:drafts and read:email, and defaults to replying only to the sender.
• The read-only halves (folder_list, draft_list, schedule_list, signature_get, automation_read) were split out of their write tools on 2026-09-09, so a read-only key is never shown a write tool. The old combined shapes (folder action: "list", draft action: "list", schedule action: "list", signature action: "get"/"set", automation action: "list"/"get"/"runs"/"preview") are still accepted on the wire for already-connected clients, but are no longer advertised.
• automation manages unattended scheduled triage rules: a stored search plus one fixed action, evaluated on a cadence with no model in the loop. There is no delete-mail action, a forward always waits for human approval, and draft_reply only ever writes a draft. See docs/automations-trust-boundary.md.
• tools/list only returns the tools your key (or OAuth token) is actually scoped for.

OAuth scopes

| Scope | Grants | | --- | --- | | read:email | List inboxes & folders; list, read, and search messages; read an inbox's signature; look up contacts | | search:email | Narrower alternative that grants only email_read's search action | | send:email | Send, reply and forward; set the signature and sender name; also required to send a draft | | manage:folders | Create/rename/delete folders; move, copy, flag and archive messages | | delete:email | Trash or permanently expunge messages | | manage:drafts | Create, edit, and delete drafts (sending one also requires send:email) | | `m