delete_email
Permanently delete an email by uid. This cannot be undone. Only delete when explicitly asked or clearly required.
LABSCO SUMMARY
A real inbox for an agent, on a mail server you run yourself.
Because MailCue is a whole mail stack in a container — Postfix, Dovecot, DKIM signing, DMARC verification, SpamAssassin — the mailbox behaves like a production one rather than a capture bucket, which is what makes it usable both for testing email flows and for handing an agent a genuine address. The single-mailbox lock decides how much rope the agent gets: set, it owns exactly one inbox and cannot address or read another; unset, it can operate the whole server.
What it is
The MCP server that ships with MailCue, a full mail stack in one container. It talks to a MailCue server over its REST API and gives an agent a real inbox: folders listed and searched, messages read in full, mail sent and replied to with threading headers set, and messages deleted.
What you get
- A mailbox folder listed newest first, each summary carrying the uid the other tools need
- Full-text search across a folder by sender, subject or body content
- One message fetched in full — body, headers and attachment metadata
- A new email sent as plain text or HTML, with cc and reply-to
- A reply by uid, with the recipient, the Re: subject and the In-Reply-To and References headers set for you
- A message deleted permanently, which its own tool description flags as irreversible
- Per-folder totals and unread counts for a mailbox
- The mailboxes on the server listed with their addresses and unread counts, when the agent is not locked to one
- An address validated on structure, DNS status, SMTP mailbox availability and whether it is disposable
- Deliverability tooling documented alongside these — scoring a message, running extended checks, listing and comparing reports, evaluating a policy — which reports a capability as unconfigured rather than inventing a result
Requirements
A running MailCue server — the whole stack is a single Docker container, reachable at http://localhost:8088 by default — and either MAILCUE_API_KEY, an mc_ key generated from the Profile page, or MAILCUE_BEARER_TOKEN. MAILCUE_BASE_URL points at your server. Launch it with npx -y mailcue-mcp@latest over stdio. The setting worth deciding first is MAILCUE_MAILBOX: with it set the agent is locked to one address — the mailbox argument disappears from every tool, sends are forced to that address, and mailbox discovery is hidden — so leave it unset only when you genuinely want an operator agent that can reach every mailbox on the server.
Setup effort
One command plus a key — npx -y mailcue-mcp@latest, then supply credentials
USE CASES
01
Giving an agent an inbox it owns
Lock it to a single mailbox, then let it list, read and reply as mail arrives.
02
Finding the message somebody is asking about
Search the folder by sender, subject or body, then open the match in full.
03
Testing an email flow end to end
Trigger the send, then check the folder counts and read what actually arrived, headers and attachments included.
04
Replying without breaking the thread
Reply by uid and let the Re: subject and threading headers be set for you.
05
Sending something new from the right address
Send as plain text or HTML from the mailbox you mean, with cc and reply-to where they belong.
06
Checking an address before you use it
Validate its structure, DNS status, SMTP availability and whether it is disposable.
07
Clearing out a test mailbox
Delete the messages you no longer need — permanently, so only when that is what was asked for.
9 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
get_email
Fetch one full email by uid: full body, headers, and attachment metadata. Read this before replying to or deleting a message.
list_emails
List emails in a mailbox folder, newest first. Returns summaries, each with a uid you can pass to get_email, reply_email, or delete_email.
list_mailboxes
List the mailboxes available on this server, with their addresses and unread counts. Use this to choose a "mailbox" argument for the other tools.
mailbox_stats
Per-folder message counts (total and unread) for a mailbox.
reply_email
Reply to an email by uid. The recipient, the "Re:" subject, and threading headers (In-Reply-To, References) are set for you. Provide "text" or "html".
search_emails
Full-text search a mailbox folder by sender, subject, or body content. Returns matching summaries with uids.
send_email
Send a new email. Provide "text" for plain or "html" for rich (at least one).
validate_email
Validate an email address structure, DNS status, mailbox SMTP availability, and disposable status.
BEFORE YOU INSTALL
What to know first
Tools you get
9 tools when we connected; the project documents 29. The remaining 20 cover address validation, suppression, deliverability and send-canary work and depend on what the connected MailCue deployment has enabled; get_deliverability_capabilities reports which are on. Setting MAILCUE_MAILBOX hides list_mailboxes.
Requires
- npx on PATH
- MAILCUE_API_KEY (or MAILCUE_BEARER_TOKEN) in your environment
INSTALLATION
Connect your client
Server setup
TERMINAL
npx -y mailcue-mcp@latestMCP Clients
Claude Code
CLAUDE CODE · TERMINAL
claude mcp add mailcue --env MAILCUE_BASE_URL=<YOUR_MAILCUE_BASE_URL> --env MAILCUE_API_KEY=<YOUR_MAILCUE_API_KEY> -- npx -y mailcue-mcp@latestAny MCP client
ANY MCP CLIENT · JSON
{
"mcpServers": {
"mailcue": {
"command": "npx",
"args": [
"-y",
"mailcue-mcp@latest"
],
"env": {
"MAILCUE_BASE_URL": "<YOUR_MAILCUE_BASE_URL>",
"MAILCUE_API_KEY": "<YOUR_MAILCUE_API_KEY>"
}
}
}
}The configuration on this page does not set MAILCUE_BEARER_TOKEN; the project's instructions put it in a .env file. To supply MAILCUE_BEARER_TOKEN without depending on where the server looks for that file, use the block's "env" section.
MailCue web UI
Developer Tools > MCP in the MailCue web UI, with MAILCUE_BASE_URL pre-filled
