# mcp-email-server

**Repository Path**: feng_guang/mcp-email-server

## Basic Information

- **Project Name**: mcp-email-server
- **Description**: MCP Email Server - 邮件服务MCP模块
- **Primary Language**: Python
- **License**: BSD-3-Clause
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-11-16
- **Last Updated**: 2026-09-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MCP Email Server

[English](README.en.md) · [贡献指南](CONTRIBUTING.md) · [BSD-3-Clause 许可证](LICENSE)

通过 MCP 提供 IMAP/SMTP 邮件查询、发送和回复，支持多个邮箱账户。维护分支为 **main**。基于 [ai-zerolab/mcp-email-server](https://github.com/ai-zerolab/mcp-email-server) 的贡献历史维护，保留原作者署名和许可证。本仓库反馈入口为 [Gitee Issues](https://gitee.com/feng_guang/mcp-email-server/issues)。上游软件包、镜像及 CI 状态不代表本仓库的发布或验证结果。

## 安装

要求 Python >=3.10,<4.0，开发环境使用 Python 3.12。准备 Git 和 uv 后：

```bash
git clone --branch main https://gitee.com/feng_guang/mcp-email-server.git
cd mcp-email-server
uv sync --frozen
uv run --frozen mcp-email-server ui
```

UI 管理账户，默认配置为 `~/.config/zerolib/mcp_email_server/config.toml`（Windows 的 ~ 为用户目录）。可通过 `MCP_EMAIL_SERVER_CONFIG_PATH` 指定其他 TOML 文件。配置含凭据，请存放在仓库外。

## MCP 客户端配置

替换仓库绝对路径；Windows 可用 `C:/Projects/mcp-email-server`。客户端需能找到 uv，否则使用其可执行文件的绝对路径。

```json
{
  "mcpServers": {
    "email": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/mcp-email-server", "run", "--frozen", "mcp-email-server", "stdio"]
    }
  }
}
```

其他命令：`ui`、`sse --host localhost --port 9557`、`reset`。reset 删除当前配置文件。SSE 默认监听本机，CLI 没有认证配置，不应直接暴露公网。

## 环境配置

可通过环境变量配置一个账户，多账户可使用 UI。四个必填变量为：

```powershell
$env:MCP_EMAIL_SERVER_EMAIL_ADDRESS = "you@example.com"
$env:MCP_EMAIL_SERVER_PASSWORD = "your-app-password"
$env:MCP_EMAIL_SERVER_IMAP_HOST = "imap.example.com"
$env:MCP_EMAIL_SERVER_SMTP_HOST = "smtp.example.com"
uv run --frozen mcp-email-server stdio
```

仅使用自己的服务商配置和应用专用密码/授权码。MCP 客户端启动的服务也需继承这些变量，或通过客户端环境设置传入。以下后缀均加 `MCP_EMAIL_SERVER_` 前缀：

| 可选后缀 | 默认值 / 用途 |
| --- | --- |
| `ACCOUNT_NAME` | default；替换同名 TOML 账户，否则新增 |
| `FULL_NAME` / `USER_NAME` | 邮箱 @ 前部分 / 邮箱地址 |
| `IMAP_PORT` / `IMAP_SSL` | 993 / true |
| `SMTP_PORT` / `SMTP_SSL` / `SMTP_START_SSL` | 465 / true / false |
| `IMAP_USER_NAME` / `IMAP_PASSWORD` | 独立 IMAP 凭据，默认使用公共凭据 |
| `SMTP_USER_NAME` / `SMTP_PASSWORD` | 独立 SMTP 凭据，默认使用公共凭据 |
| `CONFIG_PATH` | 自定义 TOML 路径 |
| `LOG_LEVEL` | INFO，诊断时可设 DEBUG |

SMTP 587/STARTTLS 通常搭配 `SMTP_SSL=false`、`SMTP_START_SSL=true`，以服务商要求为准。即使提供独立协议密码，当前仍要求公共 PASSWORD 非空。布尔真值为 true/1/yes/on。日志默认输出 stderr，没有 --debug 参数。当前没有 OAuth 登录流程。

## 工具与限制

| 工具 | 作用 |
| --- | --- |
| `list_available_accounts()` | 列出账户并掩码凭据 |
| `add_email_account(email)` | 持久化 EmailSettings 结构，见 config.py |
| `list_emails_metadata(account_name, page=1, page_size=10, ...)` | 分页查询，支持时间、主题和地址筛选 |
| `get_emails_content(account_name, email_ids)` | 通过查询返回的 ID 批量读取正文 |
| `send_email(account_name, recipients, subject, body, cc=None, bcc=None, html=False, attachments=None)` | 发送文本/HTML，附件为服务端绝对文件路径 |
| `reply_email(account_name, email_id, body, subject=None)` | 向原发件人回复 HTML，保留线程头，默认主题 Re: 加原主题 |

资源 `email://{account_name}` 返回掩码账户。正文超过 20,000 字符会截断并加 `...[TRUNCATED]`，没有读取剩余正文的工具。接收附件仅返回文件名，没有附件下载工具。发送附件必须在服务端存在。配置账户、发送和回复会产生真实变更，请控制客户端工具权限。

## Docker

```bash
docker build -t mcp-email-server:local .
docker run --rm -i --env-file /absolute/path/to/email.env mcp-email-server:local
```

环境文件保存在仓库外，以 NAME=value 设置四个必填项。默认运行 stdio，需要保持标准输入连接；附件需挂载到容器，未挂载的配置不会在删除容器后保留。

## 开发与安全维护

```bash
uv sync --frozen
uv run --frozen pytest
uv run --frozen mkdocs build --strict
```

测试前必须使用独立配置路径，见[贡献指南](CONTRIBUTING.md)。源码在 `mcp_email_server/`：app.py 注册工具，cli.py 提供命令，config.py 管理配置，emails/ 实现协议，ui.py 提供配置界面。测试在 tests/，文档站在 docs/。

main 为维护基线；小步提交、验证后合并。继承的 GitHub Actions 不会在 Gitee 自动运行。同步上游需审查差异并保留历史。

禁止提交真实密钥、密码、授权码、用户邮件或未脱敏日志。忽略规则不能保护已经跟踪的文件，每次发布前须扫描工作目录及 Git 历史，见 [SECURITY.md](SECURITY.md)。

## 许可证

采用 [BSD 3-Clause License](LICENSE)，保留 Copyright (c) 2025, ai-zerolab。感谢原作者和所有贡献者，完整贡献历史保留在 Git 中。