Skip to main content
Glama
MCP Email Server

MCP Email Server

mcp-email-server

Release Build status codecov License

An MCP server for reading, searching, organizing, and sending email through IMAP and SMTP.

NOTE

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 doctor

The 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 ui

For 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 tools
archive_emailsA
Destructive

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_mailboxA
Idempotent

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_emailsA
Destructive

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_attachmentA
Destructive

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_commandA
Destructive

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_contentA
Read-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_contentA
Idempotent

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_recipientsA
Read-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_sendersA
Read-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_accountsA
Read-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_metadataA
Read-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_tagsA
Read-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_mailboxesA
Read-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_readA
Idempotent

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_emailsA
Destructive

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_flagsA
Idempotent

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_tagsA
Idempotent

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

    A4.1/5.0

    Scored across 21 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

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

    Completeness4/5

    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

    ActivityActive
    ResponsivenessUsually handled

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Manages email accounts via IMAP/SMTP, enabling reading, searching, sending, replying, forwarding, and folder management with multi-user and OAuth support.
      22
      2
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables receiving and sending email via IMAP and SMTP across multiple accounts, with tools for listing, searching, reading, replying, and managing messages.
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables 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 npm
      MIT