MCPEmails

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 on our servers only for the request that needs them.

🔗 [mcpemails.com](https://mcpemails.com) · 📚 [Docs](https://mcpemails.com/docs) · 💳 [Pricing](https://mcpemails.com/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), 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

1. 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)

One click (OAuth): Add to Claude, Add to Cursor or Install in VS Code. Each opens the client with the server filled in; sign in (or create an account) and connect your inbox when it asks. Claude Free allows one custom connector.

Claude Code: claude mcp add --transport http mcpemails https://mcpemails.com/api/mcp

Other OAuth clients: 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](https://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 over IMAP, plus any IMAP/SMTP mailbox (Fastmail, iCloud, Yahoo, Zoho, Yandex, self‑hosted…) via app password.
• Your provider sends — outbound mail is sent through *your* provider's SMTP/API, from your real address. When a provider refuses connections from cloud addresses, the IMAP/SMTP connection goes through our own tunnel (an HTTP CONNECT relay); TLS still runs end to end to the provider, so the relay never sees mail or credentials.
• 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.
• Business‑ready: several workspaces, unlimited members with roles, and admin approval of held sends on the Business plan.

Tools

21 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.
• reminder_list - Lists the follow-ups and snoozes the server tracks: due, upcoming or all. Read-only. Pro and Business.
• reminder - Follows up on sent mail nobody replied to, and snoozes a message out of the inbox until a time you choose. Runs server-side while the chat is closed. Pro and Business.
• 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.
• draft_read - Reads one unsent draft in full, for example after the user edited it in the draft editor card. Read-only.
• draft_editor_hide - Hides or shows the in-chat draft editor card for one inbox or the whole workspace. A display preference only.

A full-scope key sees 29 tools in tools/list: the 21 above plus eight app-only tools that drive the in-chat cards rather than being composed by hand: approval_review, approval_decide, approval_update, approval_schedule (a held send), bulk_execute, bulk_cancel (a previewed bulk operation), draft_editor_save (the draft editor's Save button) and card_automation (the automation card's On/Off switch). The six `approva