MCP Email Server
The MCP Email Server provides IMAP and SMTP email functionality through an MCP interface, enabling comprehensive email account management and operations.
Key capabilities:
Add Email Accounts: Configure new accounts with IMAP/SMTP server settings including host, port, credentials, and SSL options
List Email Accounts: View all configured accounts with their attributes
Retrieve Emails: Access and paginate emails with extensive filtering options by sender, recipient, subject, body content, and date ranges
Send Emails: Compose and send emails with support for multiple recipients, CC, BCC, subject, and body
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCP Email Server check my inbox for unread emails from the last hour"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-email-server
An MCP server for reading, searching, organizing, and sending email through IMAP and SMTP.
Version 1.0.0 introduces Local Email App V2. Updating the package does not
automatically import existing settings created with PyPI 0.16.0 and earlier:
they remain active in backward-compatiblelegacy mode, so there is no required
migration. If you
would like to use the new managed storage, you can review and import those
settings whenever it is convenient.
mcp-email-server supports Windows, macOS, and Linux. See
Security for platform-specific filesystem and credential
storage details.
Optional migration for existing installations
An @latest release that includes Local Email App V2 offers a preview-first
CLI migration:
uvx mcp-email-server@latest config init \
--database ~/.config/mcp-email-server/managed.sqlite3
uvx mcp-email-server@latest config import-legacy
uvx mcp-email-server@latest config import-legacy --apply
uvx mcp-email-server@latest config doctorThe apply step displays the plan again and asks for IMPORT confirmation. A
complete import selects managed mode; otherwise the existing legacy settings
remain selected. The source TOML file and its legacy keyring entries are left
untouched. You can also run uvx mcp-email-server@latest ui and choose Import
existing settings. After a successful import, restart running MCP clients. See
the detailed upgrade guidance
and import troubleshooting.
Related MCP server: cpanel-mail-mcp
Quick start
1. Configure an email account
From this source checkout, run the configuration UI with
uv:
uv sync
uv run mcp-email-server uiFor a published release whose notes state that it includes Local Email App V2,
uvx mcp-email-server@latest ui is the equivalent temporary invocation.
Keep the foreground command running. On a truly empty installation, the authenticated browser session prepares private account storage at the safe local default; existing TOML or environment configuration instead offers an explicit import review while the previous settings keep running. The account-first UI has only Email accounts and Settings & help as primary destinations. Start with the email address and password; the UI fills common connection settings from the email domain and keeps them editable, while outgoing mail remains optional. A saved complete account is ready without a separate activation step. Use Password & test on the saved account if desired, then restart the MCP client to apply the selected settings.
2. Configure the MCP client
Use the same V2-capable distribution for stdio as for the UI. For a published V2 release, add the following server definition to the MCP client:
{
"mcpServers": {
"mcp-email-server": {
"command": "uvx",
"args": ["mcp-email-server@latest", "stdio"]
}
}
}Restart the MCP client after updating its configuration. When testing this
source checkout before publication, invoke uv run --directory /absolute/path/to/mcp-email-server mcp-email-server stdio instead of pairing a
managed catalog with PyPI @latest.
3. Verify the connection
Ask the client to list the configured email accounts or recent messages.
Other configuration methods
For the SQLite-backed managed CLI workflow, Windows and POSIX storage boundaries,
headless environments, multiple accounts, custom TLS settings, and
environment-variable configuration, see the
documentation. Release 1.6.2 and later
also publish Linux amd64/arm64 images at
ghcr.io/wh1isper/mcp-email-server; see the
container instructions.
Documentation
Development
See CONTRIBUTING.md.
License
This project is licensed under the terms of the LICENSE.
Available Tools
21 toolsarchive_emailsADestructive
Archive one or more emails by moving them to the account's Archive folder, auto-detected via the RFC 6154 \Archive flag (falling back to common names like Archive or [Gmail]/All Mail). Use list_emails_metadata first. Partial or ambiguous effects report per-ID succeeded/failed/unknown status and are not retried automatically.
Inputs: email_ids (required), account_name (required), mailbox. Returns: result
create_mailboxAIdempotent
Create one mailbox/folder by its exact server name, including the hierarchy delimiter reported by list_mailboxes (for example 'Archive/Projects' or 'INBOX.Projects'). Requires the organize permission. Idempotent: an existing mailbox reports already_exists without changes. Parent levels are created only if the server does so itself. An unknown status is not retried automatically; verify with list_mailboxes.
Inputs: mailbox (required), account_name (required). Returns: Outcome of an explicit mailbox creation request
delete_emailsADestructive
Delete one or more emails by email_id using target-scoped UID EXPUNGE. Use list_emails_metadata first. Partial or ambiguous effects report per-ID succeeded/failed/unknown status and are not retried automatically.
Inputs: email_ids (required), account_name (required), mailbox. Returns: result
download_attachmentADestructive
Download an email attachment. By default it is saved with a safe randomized name under the current user's Downloads/mcp-email-server directory; an explicit destination path remains supported. This feature must be explicitly enabled in settings (enable_attachment_download=true) due to security considerations.
Inputs: email_id (required), account_name (required), attachment_name (required), mailbox, +1 more. Returns: Attachment download response
email_commandADestructive
Execute IMAP or SMTP primitives when a focused email tool does not cover the operation. Existing tools, including create_mailbox, remain the simpler policy-aware route. Start with commands=[{"command":"HELP"}] or HELP UID COPY for local syntax and examples; no account is needed for help. Execution requires account_name and user-enabled allow_protocol_commands with compatible policy. Commands run in order on one automatically authenticated connection; state lasts only for this call. For example SELECT a mailbox, then UID COPY known UIDs to an existing destination. Put APPEND/DATA message content in data, never in command lines. No login commands, passwords, hosts, shell scripts or local paths. Stops on the first error. Inspect every result: prior effects may exist and unknown completion must not be replayed automatically. HELP lists supported syntax; server CAPABILITY alone does not imply client support for arbitrary extensions.
Inputs: commands (required), protocol, account_name. Returns: error, status, results, warnings
forward_emailA
Forward an existing message to new recipients using the specified account. The source message is read over IMAP first: if it cannot be read, the call fails before any SMTP session is opened, so a forward is never delivered without the content it was supposed to carry. The subject is derived from the source as 'Fwd: ' without stacking a second prefix, the caller's note is placed above a plain-text forwarded block re-composed from the source's parsed text body, and the source's attachments are re-attached with their original MIME types unless include_attachments is false. Partial or ambiguous SMTP delivery reports per-recipient succeeded/failed/unknown status and reports the independent Sent-copy outcome separately; ambiguous effects are not retried automatically. The response names the delivered message's RFC Message-Id once the provider accepts the message data, and reports no identifier for an ambiguous delivery.
Inputs: email_id (required), recipients (required), account_name (required), cc, +4 more. Returns: result
get_attachment_contentARead-onlyIdempotent
Read one email attachment as an MCP embedded binary resource without writing a local file. This independent transfer mode requires enable_attachment_content=true.
Inputs: email_id (required), account_name (required), attachment_name (required), mailbox.
get_emails_contentAIdempotent
Get the body, reply-thread headers, and selected top-level headers of one or more emails by email_id. Use list_emails_metadata first. This tool is non-read-only because mark_as_read=true changes remote flags.
Inputs: email_ids (required), account_name (required), mailbox, body_offset, +3 more. Returns: Batch content, optionally handed off as a private local JSON artifact.
list_allowed_recipientsARead-onlyIdempotent
List the configured recipient allowlist — the address patterns that send_email and forward_email are permitted to send to and save_to_mailbox is permitted to address. Matching is case-insensitive and supports glob patterns such as *@example.com; * explicitly allows all recipients. An empty list denies all recipients for these operations; configure patterns through the user-operated CLI/UI.
Inputs: no named parameters. Returns: result
list_allowed_sendersARead-onlyIdempotent
List the configured inbound sender allowlist — the address patterns whose mail the server will read or act on. When configured, only these senders' mail is visible to the read tools (list_emails_metadata, get_emails_content, download_attachment, and forward_email's source read) and eligible for the mutation tools (delete_emails, set_email_flags, mark_emails_as_read, move_emails, archive_emails). Returns an empty list when unrestricted.
Inputs: no named parameters. Returns: result
list_available_accountsARead-onlyIdempotent
List configured accounts as stable non-secret capability records. Use only accounts with can_receive=true for mail reads and can_send=true for send_email and forward_email. If the result is empty, ask the user to run mcp-email-server ui or the user-operated CLI; never ask for credentials in chat.
Inputs: no named parameters. Returns: result
list_emails_metadataARead-onlyIdempotent
List email metadata (email_id, subject, sender, recipients, date) without body content. Time filtering and ordering use provider INTERNALDATE; the returned date is the message's RFC 5322 Date header. Returns email_id for use with get_emails_content.
Inputs: account_name (required), body, page, seen, +14 more. Returns: Paged email metadata response
list_email_tagsARead-onlyIdempotent
List the configured semantic IMAP tags for one account. The name and description support natural-language selection; writable is false unless explicitly enabled in the account configuration.
Inputs: account_name (required). Returns: result
list_mailboxesARead-onlyIdempotent
List available mailboxes/folders for an email account. Returns folder names, hierarchy delimiters, and flags. Useful for discovering folder names before moving emails.
Inputs: account_name (required), pattern, reference. Returns: result
mark_emails_as_readAIdempotent
Mark one or more emails as read by email_id. This is the common-workflow equivalent of adding \Seen with set_email_flags. Use list_emails_metadata first. Partial or ambiguous effects report per-ID succeeded/failed/unknown status and are not retried automatically.
Inputs: email_ids (required), account_name (required), mailbox. Returns: result
move_emailsADestructive
Move emails between IMAP folders using UIDs from list_emails_metadata in source_mailbox. Specify exactly one of destination_mailbox or destination_role='junk' to discover the Junk folder via \Junk, then common names. Missing or ambiguous discovery requires an explicit destination; no folder is created. To restore from Junk, list it again for current UIDs and move to INBOX with that explicit source_mailbox. This requests a move, not guaranteed spam training or reporting. Partial or ambiguous effects report per-ID succeeded/failed/unknown status and are not retried.
Inputs: email_ids (required), account_name (required), source_mailbox, destination_role, +1 more. Returns: result
save_draftA
Compose and save an unsent draft to the configured drafts mailbox or unique special-use Drafts mailbox. Requires draft permission, not append or send. Recipients may be omitted; supplied recipients obey the recipient allowlist. The Draft flag is fixed; no arbitrary target or flags.
Inputs: body (required), subject (required), account_name (required), cc, +6 more. Returns: result
save_to_mailboxA
Compose an email and save it to an IMAP folder (e.g., Drafts). Shares recipient, body, attachment, and threading parameters with send_email; adds mailbox and flags, and does not support reply_to. Default folder is Drafts with \Draft and \Seen flags. Pure IMAP operation — works without SMTP configuration. An ambiguous APPEND is reported as unknown and is not retried automatically.
Inputs: body (required), subject (required), recipients (required), account_name (required), +8 more. Returns: result
send_emailA
Send one email using the specified account. Supports reply threading. Partial or ambiguous SMTP delivery reports per-recipient succeeded/failed/unknown status and reports the independent Sent-copy outcome separately; ambiguous effects are not retried automatically. The response names the delivered message's RFC Message-Id once the provider accepts the message data, and reports no identifier for an ambiguous delivery.
Inputs: body (required), subject (required), recipients (required), account_name (required), +7 more. Returns: result
set_email_flagsAIdempotent
Add or remove approved IMAP flags on one or more emails by email_id. Supported flags are \Seen, \Flagged, \Answered, and \Draft; \Deleted and provider-specific keywords are not supported. Use list_emails_metadata first. Partial or ambiguous effects report per-ID succeeded/failed/unknown status and are not retried automatically.
Inputs: flags (required), email_ids (required), operation (required), account_name (required), +1 more. Returns: result
set_email_tagsAIdempotent
Add or remove configured writable semantic tags on emails. Only semantic names are accepted; standard flags and unrelated provider keywords are preserved.
Inputs: tags (required), email_ids (required), operation (required), account_name (required), +1 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
Most tools target clearly distinct resource+action pairs (metadata vs. content vs. attachment vs. mailbox). A few overlaps create mild confusion: save_to_mailbox vs. save_draft (both compose unsent mail), mark_emails_as_read vs. set_email_flags (explicitly the same \Seen effect), and archive_emails vs. move_emails, though the descriptions do distinguish them.
Strong, predictable verb_noun snake_case throughout: list_*, get_*, send_*, set_*, save_*, delete_*, move_*, archive_*, create_*, download_*. The only notable deviation is email_command (noun_verb escape hatch) and the get_* vs. download_* split for attachments, but it remains readable and mostly uniform.
21 tools is on the heavy side for an email server and lands in the borderline 16-25 band. Each tool does map to a real operation (accounts, allowlists, tags, mailboxes, flags, drafts, attachments, protocol escape), but the surface feels broad and could be consolidated (e.g. save_draft into save_to_mailbox).
The domain is well covered: read metadata/content/attachments, send, forward, drafts, flags, tags, move/archive/delete, mailbox list/create, account and allowlist inspection, plus a protocol escape hatch. Minor gaps exist around mailbox lifecycle (rename/delete folder not offered) and there is no dedicated search tool, but email_command can work around these.
Maintenance
Related MCP Connectors
Email, calendar and contacts for AI agents: Gmail, Microsoft 365 and IMAP accounts behind one API.
Send and receive email from your verified domains; manage domains, templates and deliverability.
Email infrastructure and authentication for developers: domains, inbox routes, auth apps, deploys.
Send, track, and manage transactional and bulk email delivery
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables sending and receiving emails through SMTP, IMAP, and POP3 protocols with support for attachments, HTML content, and email validation.MIT
- AlicenseAqualityBmaintenanceManages email accounts via IMAP/SMTP, enabling reading, searching, sending, replying, forwarding, and folder management with multi-user and OAuth support.222MIT
- AlicenseNot gradedqualityCmaintenanceEnables receiving and sending email via IMAP and SMTP across multiple accounts, with tools for listing, searching, reading, replying, and managing messages.MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI assistants to search, read, send, reply, forward, organize, and bulk-delete emails across multiple IMAP and SMTP mailboxes with AES-256-encrypted credential storage and connection pooling. Supports 15+ pre-configured providers including Gmail, Outlook, Yahoo, and iCloud through a web-based setup wizard.1,009 npmMIT