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 · 📚 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
- 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.
- 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_…). - Point your client at the server. The MCP endpoint is a single URL:
https://mcpemails.com/api/mcp - Your agent works the inbox. It calls tools like
inbox_list,email_read(action: "search"),email_compose(action: "send"), andschedule(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 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
SEARCHare normalized behind oneemail_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 approval_* and bulk_* tools always carry _meta.ui.visibility: ["app"]; draft_editor_save carries it where the draft editor is on and refuses every call where it is off; card_automation is listed only where the card is on.
prompts/list holds 7 user-invoked workflow prompts (morning_inbox_triage, find_and_brief, follow_up_radar, decision_tracker, prepare_reply_drafts, clean_up_safely, review_scheduled_sends), each listed only to a key holding its scopes.
Notes:
- Tools accept either an explicit
inbox_id(UUID) or aninboxemail address; single‑inbox keys auto‑resolve the target. - Batch actions cap at 50 (
email_read'sread_batch) to 500 (move/delete/flag) messages per call. - For a targeted mutation, first use
email_readwithaction: "search", then pass the returnedmessage_idormessage_idstoemail_organizeoremail_delete. Search fields are accepted only byemail_search_and_moveandemail_delete'ssearch_and_deleteaction. contact_searchscans recent mail live, so there is no stored address book.email_read'soriginalaction returns one complete provider-stored MIME message as a portable.emlfile (up to 25 MB). It is read-only and never marks the message as read.draft'ssendaction requiressend:email, notmanage:drafts, so a key that can only manage drafts can't use them to bypass the send‑mail consent.draft'sreplyaction creates an unsent, provider-native reply in the source conversation. It needs bothmanage:draftsandread: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 (folderaction: "list",draftaction: "list",scheduleaction: "list",signatureaction: "get"/"set",automationaction: "list"/"get"/"runs"/"preview") are still accepted on the wire for already-connected clients, but are no longer advertised. automationmanages 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, aforwardalways waits for human approval, anddraft_replyonly ever writes a draft. Seedocs/automations-trust-boundary.md.
OAuth scopes
Supported providers
Mail on your own domain at a web host connects like any IMAP mailbox, and one workspace can hold several of them (info@, sales@, support@). Per-host settings and known pitfalls for 100 providers are at mcpemails.com/connect. Feature support per provider is in the provider compatibility matrix, and the probed IMAP/SMTP hosts, login mechanisms and size limits are free to download as an open provider dataset (JSON and CSV, CC BY 4.0).
Outlook uses Microsoft Graph with "Sign in with Microsoft", not IMAP. Personal Microsoft accounts (outlook.com, hotmail.com, live.com, msn.com) connect directly. On work or school Microsoft 365 tenants, Microsoft's default consent policy stops employees approving mail permissions themselves, so an IT admin approves the app once for the organisation; the dashboard gives the user a shareable approval link to send them (
/auth/outlook/admin-consent), and the admin needs no MCPEmails account. A Microsoft account with no Exchange Online mailbox is refused, with a pointer to IMAP. The label tools are Gmail-only (Outlook uses folders), except that an automation's label action applies an Outlook category; and Graph cannot combine a text search with the unread, attachment, flagged or date filters.
Pricing
The value metric is connected inboxes. Free connects one mailbox, Personal connects up to three, Pro connects up to 10 for one person running a business, and Business includes 10 mailboxes, charges $3 a month for each extra one, and adds unlimited people with roles and a separate workspace per client. Annual billing saves about 20%.
Per‑API‑key limits also apply (100 req/min · 1,000/hr · 10,000/day). Rate limits are retryable: they come back as JSON-RPC error -32003 with data.retry_after in seconds.
Free workspaces get 150 email actions per calendar month (UTC). The first 3 days after signup are not counted (7 days for workspaces created before 2026-10-17), and inbox_list and the dashboard are never counted. When the allowance is reached, every other email action is refused until the 1st of the next month, unattended automations pause and resume automatically on the 1st, and the owner is emailed at 80% and at 100%. Personal, Pro and Business have no monthly cap, subject to fair use (their ceilings are abuse guards, not plan features, and are not printed anywhere). A refusal is not retryable and not a JSON-RPC error: it comes back as a normal tool result with isError: true, text that opens with the count and the reset date, and a _meta["com.mcpemails/usage_limit"] block that clears at reset_at.
Internal plan ids predate the names: solo is sold as Pro and pro is sold as Business (it was Team until 2026-10-19). The newer personal id is the only one that matches its display name, Personal. Every user who existed before the 2026-08-19 repricing keeps unlimited inboxes for free, permanently, every workspace already on Pro when the 10-inbox cap arrived keeps unlimited inboxes, and every workspace created before the 2026-09-12 launch of the action allowance is an early member that is not metered against it. See apps/web/src/lib/stripe/plans.ts.
Architecture
flowchart LR
Agent["MCP client<br/>(Claude, Cursor, …)"] -->|"JSON-RPC / OAuth or API key"| Web
subgraph Vercel["Vercel — Next.js 16"]
Web["/api/mcp route<br/>+ marketing site + dashboard"]
end
subgraph Supabase
Edge["mcp-server<br/>edge function (Deno)"]
DB[("Postgres<br/>RLS + encrypted creds")]
Cron["outlook-token-refresh<br/>edge function"]
end
Web -->|proxies| Edge
Edge -->|decrypt creds, fetch live| Providers["Email providers<br/>Gmail API · Microsoft Graph · IMAP/SMTP"]
Edge --> DB
Cron --> DB
Web --> Stripe[("Stripe<br/>billing")]
/api/mcpis a thin Next.js route handler that proxies to the Supabase edge functionmcp-server— the real MCP implementation, where credentials are decrypted and provider calls are made.- The Postgres database stores workspaces, members, inboxes (encrypted tokens/passwords), hashed API keys, OAuth clients, scheduled sends, and an activity log — all guarded by Row‑Level Security.
- A cron edge function (
outlook-token-refresh) refreshes Outlook OAuth tokens before expiry.
Stack: Next.js 16 (App Router) · React 19 · next‑intl 4 · Supabase (Auth, Postgres, Edge Functions) · Stripe · Resend · TypeScript. Email parsing and sanitization run in the edge functions (supabase/functions/mcp-server/mime.ts); signature HTML is sanitized with DOMPurify in the browser and a dependency-free allow-list on the server.
Repository layout
.
├── apps/
│ └── web/ # Next.js 16 app (marketing, dashboard, /api/mcp proxy)
│ ├── app/ # App Router routes ([locale], dashboard, api, auth)
│ ├── components/ # marketing/ + dashboard/ React components
│ ├── messages/ # next-intl translations (en, nb, es, fr, zh)
│ ├── src/lib/ # stripe/, supabase/, blog/, crypto helpers
│ └── proxy.ts # middleware: i18n + Supabase session + CDN cache
├── supabase/
│ ├── functions/
│ │ ├── mcp-server/ # the MCP server (tools, auth, scopes)
│ │ └── outlook-token-refresh/
│ └── migrations/ # SQL migrations (schema + RLS)
└── package.json # npm workspaces (apps/*)
Local development
Prerequisites: Node.js 20+, npm, and the Supabase CLI (for migrations and edge functions).
# 1. Install (npm workspaces — run from the repo root)
npm install
# 2. Configure environment
cp .env.example apps/web/.env.local
# then fill in the values (see below) and generate the two secrets:
openssl rand -hex 32 # ENCRYPTION_KEY
openssl rand -hex 32 # CSRF_SECRET
# 3. Run the web app (http://localhost:3000)
npm run dev
# 4. Production build
npm run build
next.config.jsvalidates required env vars at build/start and rejects weakENCRYPTION_KEYvalues, so a misconfigured environment fails fast instead of at runtime.
Environment variables
Copy .env.example and fill in real values. Required in every environment:
Feature‑dependent:
Fastmail and other IMAP providers connect via app password and need no OAuth credentials.
Stripe webhooks are delivered through a queue. Stripe posts to the Queuey ingress, which forwards to
/api/stripe/webhook. Two settings on that queue are load‑bearing: the payload must be raw passthrough (the signature is over exact bytes), and a mapped header must forwardheader:Stripe-Signature. Without the mapped header every delivery fails withMissing stripe-signature header.Note thatSTRIPE_WEBHOOK_SECRETmust be the signing secret of the Stripe endpoint pointed at the ingress, not of any older direct endpoint.
Database & migrations
Schema and Row‑Level Security policies live in supabase/migrations/. Core tables: workspaces, workspace_members, inboxes (encrypted credentials, soft‑deleted), api_keys (hashed, scoped, inbox‑restricted), oauth_clients, scheduled_sends, workspace_invites, and a month‑partitioned activity_log.
# Apply one migration to the linked project, then record it in the history
npx supabase db query --linked -f supabase/migrations/<file>.sql
npx supabase migration repair --status applied <version> --linked
# Regenerate TypeScript types from the live schema
npm run gen:types
The Supabase CLI is the source of truth for DB changes in this project.
apps/web/src/types/database.types.ts is GENERATED
It is written in full by npm run gen:types (supabase gen types typescript --linked), which reads the live linked project, not the migration files.
Do not hand-edit it: a hand-added column is silently dropped by the next
regeneration, and a hand-added column that never existed in the database
compiles clean and 500s in production. Regenerate it in the same change that
applies a migration, and commit the result.
Tables, views and RPC functions are all covered, and every Supabase client
declared in the .ts/.tsx of apps/web (which is the whole typechecked
program) is SupabaseClient<Database>, so .from(), .select(), .insert()
and .rpc() are type-checked against the real schema. If a table or column
looks missing, the fix is npm run gen:types, never a local as any on the
Supabase client. Casts that remain are for things the generator genuinely
cannot express: jsonb payload shapes, nullable function arguments, and one
helper that dispatches many RPCs through a single signature. Each of those
carries a comment saying so.
The .ts/.tsx qualifier is load-bearing. apps/web/tsconfig.json sets no
checkJs and its include is **/*.ts and **/*.tsx, so a .js file such as
app/dashboard/[[...section]]/page.js is outside the program entirely: its
JSDoc @param types are documentation and nothing verifies them. They are
written as SchemaTypedClient (a @typedef for
SupabaseClient<Database>) so the documentation at least agrees with what the
callers pass, but keeping it honest is a manual job.
Never write a bare SupabaseClient. With no type argument it resolves to
SupabaseClient<any, "public", any>, which is an as any that no grep for
as any will find: a function declared db: SupabaseClient gets no column
checking at all, and a nonexistent column in an .insert() compiles clean.
SupabaseClient<any> is the same hole spelled out loud, and so are
SupabaseClient<any | Database> and SupabaseClient<Alias> where the alias is
any. apps/web/eslint.config.mjs therefore does not hunt for any; it
requires Database, and npm run lint errors on any SupabaseClient type
reference that does not carry it, plus an un-parameterised
createServerClient(...) / createBrowserClient(...).
Those are syntactic selectors (the repo runs no type-aware linting), so they
match on the spelling at the use site and three things could otherwise walk
straight past them: import { SupabaseClient as SB }, import * as Supa then
Supa.SupabaseClient, and const mk = createServerClient; mk(...). No selector
can see through any of those, so the config closes them one level up instead:
renaming the SupabaseClient import and namespace-importing @supabase/ssr or
@supabase/supabase-js are themselves errors, and no-restricted-imports
keeps createClient / createServerClient / createBrowserClient out of every
file except the wrappers in src/lib/supabase/, which are the one place that
constructs a client and always passes <Database>. Everything else imports
those wrappers.
The rules are not scoped to **/*.ts(x), so the import and call restrictions
apply in .js/.jsx/.mjs too. What they cannot do there is read a JSDoc
type: a syntactic selector sees no AST node for it. That is the known limit
above, not a gap the rules pretend to cover.
Two things a green tsc still does not tell you:
--linkedreads production, notsupabase/migrations/. Whatever the live project actually has is what lands in the file, drift included, and a migration that exists locally but has not been pushed is invisible to it. Regenerating needs credentials for the linked project, so CI cannot reproduce this file from the repo alone. Checksupabase migration list --linkedbefore believing the types describe what the migrations say. As of 2026-09-16 that command reports eight mismatches in both directions.- A cast still switches checking off.
(row as any).some_columnandclient as unknown as SupabaseClient<Database>both compile whatever you write. The lint rules above catch the client declaration, not a client that is cast toanyat the call site;@typescript-eslint/no-explicit-anyis what catches those, and aneslint-disableon it is a deliberate choice that should say why.
Deployment
Web app → Vercel (project mcp-emails-web):
vercel --prod --yes
Security headers and function timeouts are defined in vercel.json. The marketing routes are served with a CDN‑cacheable Cache-Control (set in proxy.ts) so crawlers and repeat visitors hit the edge cache; the dashboard, auth, and API routes stay no-store.
MCP server → Supabase edge function:
npx supabase functions deploy mcp-server --project-ref <your-project-ref> --no-verify-jwt
Migrations first, function second. PostgREST does not return
undefinedfor a column it does not know about — it errors — and the server's shared inbox projection (INBOX_SELECT_COLUMNS) is used by every mail tool, which all read a query error as "inbox not found". Deploying the function ahead of its migration can therefore take the whole mail surface down, not just the feature that wanted the new column. Newly-migrated inbox columns are deliberately read in their own small queries (readSendReviewMode,readBulkReviewMode,readInboxDraftEditorHidden) so an out-of-order deploy degrades that one feature instead of breaking everything — that is a safety net, not a licence to skip the order.
Self-hosting
Don't want to trust the hosted service with your mail? Run the same MCP server on your own
machine. self-host/ ships a containerized stack (Postgres + PostgREST + the Deno
server, no Supabase/Stripe/dashboard), so your credentials are encrypted with a key only you hold
and decrypted only inside your own container. The self-hosting guide compares it with the hosted service.
cd self-host
make setup # generate secrets (.env)
make up # build + start the stack
export IMAP_PASSWORD='your-app-password'
make provision [email protected] IMAP_HOST=imap.fastmail.com SMTP_HOST=smtp.fastmail.com SERVICE=fastmail
make key NAME="my agent" # mint an mcpe_ key, then point your client at http://localhost:8787
It is IMAP/SMTP-first (Fastmail, iCloud, Yahoo, Zoho, Yandex, generic) via app password; Gmail/Outlook
OAuth and the web dashboard remain hosted-only (Outlook would also need your own Microsoft Entra app registration). The container runs supabase/functions/mcp-server/
unmodified; see self-host/README.md for the full guide.
Internationalization
Built with next‑intl (localePrefix: 'as-needed', localeDetection: false for stable canonical URLs). English is served at /; other locales carry a prefix (/nb, /es, /fr, /zh). Translations live under apps/web/messages/.
Supported locales: English, Norwegian Bokmål, Spanish, French, Chinese (Simplified).
Security model
- Credentials encrypted at rest with AES‑256‑GCM; decrypted on the server only for the request that needs them (the
mcp-serveredge function, and the web API routes that check or test a connection). - No message storage — email bodies and attachments are fetched live and never persisted. Attachment text extraction runs transiently in the request and returns no raw attachment bytes.
- API keys are hashed (only a prefix is stored for display) and scoped per permission and per inbox, with optional expiry.
- OAuth 2.0 + PKCE for client authorization; Dynamic Client Registration (RFC 7591) for MCP clients.
- Row‑Level Security isolates every workspace's data at the database layer.
- Strict CSP, HSTS,
X-Frame-Options: DENY, and related headers on every response.
License
MCPEmails is open source under the GNU Affero General Public License v3.0 (AGPL‑3.0). The hosted service at mcpemails.com runs the same server you can self-host, so you can read the code, verify it, and run it yourself. See /security for the trust model.
Send and receive email from any agent. © MCPEmails, AGPL‑3.0.
