mcp-email-server

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-compatible `legacy` 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.

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, containers, multiple accounts, custom TLS settings, and

environment-variable configuration, see the

documentation.

Documentation

• Getting Started
• Configuration
• MCP Tools
• Transports
• Security
• Troubleshooting

Development

See CONTRIBUTING.md.

License

This project is licensed under the terms of the LICENSE.