Metadata-Version: 2.4
Name: mcp-email-server
Version: 1.3.1
Summary: IMAP and SMTP via MCP Server
Project-URL: Homepage, https://mcp-email-server.wh1isper.top/
Project-URL: Repository, https://github.com/Wh1isper/mcp-email-server
Project-URL: Documentation, https://mcp-email-server.wh1isper.top/
Author-email: wh1isper <jizhongsheng957@gmail.com>
License-File: LICENSE
Keywords: IMAP,MCP,SMTP,email
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <4.0,>=3.11
Requires-Dist: aioimaplib>=2.0.1
Requires-Dist: aiosmtplib>=4.0.0
Requires-Dist: anyio>=4.5
Requires-Dist: beautifulsoup4>=4.14.3
Requires-Dist: click>=8.0.0
Requires-Dist: filelock>=3.32.2
Requires-Dist: jinja2>=3.1.5
Requires-Dist: keyring>=25.0
Requires-Dist: loguru>=0.7.3
Requires-Dist: mcp[cli]<2,>=1.23.0
Requires-Dist: pydantic-settings[toml]>=2.11.0
Requires-Dist: pydantic>=2.11.0
Requires-Dist: pywin32>=312; sys_platform == 'win32'
Requires-Dist: starlette>=0.40
Requires-Dist: tomli-w>=1.2.0
Requires-Dist: typer>=0.15.1
Requires-Dist: tzdata>=2025.2; sys_platform == 'win32'
Requires-Dist: uvicorn>=0.30
Description-Content-Type: text/markdown

# mcp-email-server

[![Release](https://img.shields.io/github/v/release/Wh1isper/mcp-email-server)](https://github.com/Wh1isper/mcp-email-server/releases)
[![Build status](https://img.shields.io/github/actions/workflow/status/Wh1isper/mcp-email-server/main.yml?branch=main)](https://github.com/Wh1isper/mcp-email-server/actions/workflows/main.yml?query=branch%3Amain)
[![codecov](https://codecov.io/gh/Wh1isper/mcp-email-server/graph/badge.svg?token=0mToRybKx8)](https://codecov.io/gh/Wh1isper/mcp-email-server)
[![License](https://img.shields.io/github/license/Wh1isper/mcp-email-server)](https://github.com/Wh1isper/mcp-email-server/blob/main/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-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](docs/security.md) 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:

```bash
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](docs/getting-started.md#upgrading-to-local-email-app-v2)
and [import troubleshooting](docs/troubleshooting.md#legacy-import-reports-a-conflict-or-missing-credential).

## Quick start

### 1. Configure an email account

From this source checkout, run the configuration UI with
[`uv`](https://docs.astral.sh/uv/):

```bash
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:

```json
{
  "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](https://mcp-email-server.wh1isper.top/).

## Documentation

- [Getting Started](https://mcp-email-server.wh1isper.top/getting-started/)
- [Configuration](https://mcp-email-server.wh1isper.top/configuration/)
- [MCP Tools](https://mcp-email-server.wh1isper.top/tools/)
- [Transports](https://mcp-email-server.wh1isper.top/transports/)
- [Security](https://mcp-email-server.wh1isper.top/security/)
- [Troubleshooting](https://mcp-email-server.wh1isper.top/troubleshooting/)

## Development

See [CONTRIBUTING.md](https://github.com/Wh1isper/mcp-email-server/blob/main/CONTRIBUTING.md).

## License

This project is licensed under the terms of the [LICENSE](https://github.com/Wh1isper/mcp-email-server/blob/main/LICENSE).
