Albretsen/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:
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:
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.