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 Gmail (one‑click OAuth) 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:
   Code

   Copy

   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 — Gmail via OAuth, 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, IMAP SEARCH, and JMAP 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.

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.