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:

   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.

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 — G

... View full README on GitHub