Mailbridge MCP
自托管的MCP服务器，允许Claude.ai通过可流式HTTP对IMAP/SMTP电子邮件帐户进行读/写访问。
Claude.ai ──HTTPS──> Nginx (Proxmox host) ──HTTP:8765──> mailbridge-mcp (LXC)
├── IMAP/TLS ──> mail servers
└── SMTP/TLS ──> mail serversPython 3.13、FastMCP 3.x、GitHub OAuth（用于Claude.ai web访问）、structlog JSON日志。在专用的Proxmox LXC容器（Debian 13 Trixie）中作为systemd服务运行，通过Nginx使用TLS代理。
工具
11个MCP工具，跨越多个电子邮件帐户的读写操作：
| 工具 | 说明 |
|---|---|
imap_list_accounts | 列出带有ID和标签的已配置帐户 |
imap_list_folders | 列出所有包含邮件/未读计数的IMAP文件夹 |
imap_list_messages | 分页消息摘要（JSON或markdown） |
imap_get_message | 完整消息内容，HTML转明文，50K正文截断 |
imap_search_messages | 按文本、发件人、日期范围、标志搜索 |
imap_get_thread | 通过消息ID/References标头进行线程重建 |
imap_send_email | 编写和发送带有地址验证和速率限制 |
imap_reply | 回复正确 In-Reply-To/References 穿线 |
imap_move_message | 在文件夹之间移动（复制+删除模式） |
imap_delete_message | 移动到垃圾桶（自动检测）；永不删除 |
imap_set_flags | 标记已读/未读、标记/未标记 |
所有工具在失败时都会返回结构化JSON错误。附件内容永远不会返回到模型（仅元数据）。
快速开始
git clone https://github.com/L3DigitalNet/mailbridge-mcp.git
cd mailbridge-mcp
uv venv --python 3.13 .venv
source .venv/bin/activate
uv pip install -e ".[dev]"复制并编辑配置文件：
cp .env.example .env
cp config/accounts.yaml.example config/accounts.yaml
# Edit both files with your credentials服务器需要GitHub OAuth凭据才能启动（它拒绝在没有身份验证的情况下运行）：
# Set these in .env:
# GITHUB_OAUTH_CLIENT_ID=
# GITHUB_OAUTH_CLIENT_SECRET=
# MCP_PUBLIC_HOST=运行服务器：
python -m mailbridge_mcp.server
# Listening on http://0.0.0.0:8765
# Health check: curl http://localhost:8765/health认证
Claude.ai的web界面要求远程MCP服务器使用OAuth 2.1（它不支持原始Bearer令牌）。此服务器使用FastMCP的内置 GitHubProvider 以处理OAuth流。
设置：
- 创建一个 回调URL设置为
https:///auth/callback - 集
GITHUB_OAUTH_CLIENT_ID和GITHUB_OAUTH_CLIENT_SECRET在.env - 当从Claude.ai连接时，只需输入基本URL（例如。，
https://mcp.example.com)-没有/mcp后缀 - Claude.ai通过GitHub重定向您进行授权，然后您就连接了
克劳德代码： 使用 claude mcp add 随着 --transport http 和 --header 用于直接访问承载令牌。
配置
环境变量(.env)
| 变量 | 默认值 | 用途 |
|---|---|---|
GITHUB_OAUTH_CLIENT_ID | （必填） | GitHub OAuth应用程序客户端ID |
GITHUB_OAUTH_CLIENT_SECRET | （必填） | GitHub OAuth应用程序客户端密码 |
MCP_PUBLIC_HOST | （必填） | OAuth回调的公共主机名 |
MCP_HOST | 0.0.0.0 | 收听地址 |
MCP_PORT | 8765 | 监听端口 |
IMAP_TIMEOUT | 30 | 超时前每个IMAP操作的秒数 |
SMTP_TIMEOUT | 30 | 超时前每次SMTP发送的秒数 |
LOG_LEVEL | INFO | DEBUG, INFO, WARNING，或 ERROR |
SMTP_RATE_LIMIT | 10 | 所有工具每分钟的最大发送次数（0=无限制） |
ACCOUNTS_CONFIG_PATH | /etc/mailbridge-mcp/accounts.yaml | 帐户定义路径 |
账户定义(accounts.yaml)
每个帐户指定IMAP和SMTP连接详细信息。密码使用 ${VAR} 启动时从环境变量解析占位符；它们从未出现在YAML中。
accounts:
- id: personal
label: "Personal (me@example.com)"
imap:
host: mail.example.com
port: 993
tls: true
username: me@example.com
password: "${PERSONAL_IMAP_PASSWORD}"
smtp:
host: mail.example.com
port: 587
starttls: true
username: me@example.com
password: "${PERSONAL_SMTP_PASSWORD}"
default_from: "My Name "部署
设计文件(docs/mailbridge-mcp-design.md)有完整的部署说明。简短版本：
- LXC容器： 在Proxmox上使用静态IP和Python 3.13创建一个无特权的Debian 13容器。
- 安装： 将仓库克隆到
/opt/mailbridge-mcp，创建一个venv，pip install -e .，部署.env和accounts.yaml随着chmod 600.
- 系统服务： 该装置作为专用设备运行
mailbridge用户：
ExecStart=/opt/mailbridge-mcp/.venv/bin/python -m mailbridge_mcp.server- Nginx反向代理 Proxmox主机上的HTTPS将转发到容器。禁用此vhost的全局速率限制（OAuth流是突发的）：
location / {
limit_req zone=api burst=200 nodelay;
proxy_pass http://:8765;
proxy_buffering off;
proxy_read_timeout 300s;
}- 连接Claude.ai： 设置>集成>添加自定义集成。输入您的基本URL（例如。，
https://mcp.example.com).Claude.ai重定向到GitHub OAuth进行授权。
CI/CD
GitHub操作运行 ruff check, mypy，以及 pytest 每一次推。部署工作流SSH在合并时部署到LXC main.
发展
ruff check . # lint
ruff format . # format
mypy mailbridge_mcp/ # type check
pytest # run tests
pytest tests/test_config.py # single file
pytest -k "test_send" # single test by name
pytest --cov=mailbridge_mcp # coverage report108个测试，涵盖配置、IMAP客户端、SMTP客户端、格式化程序、身份验证中间件、工具行为、MCP合约验证和输入验证。
安全
- 通过FastMCP的GitHub OAuth 2.1
GitHubProvider（适用于Claude.ai网络访问） - 未配置身份验证，服务器拒绝启动
- 凭据仅存在于环境变量中，从不存在于代码或YAML中
- 对错误消息进行清理：在返回模型之前，删除电子邮件地址、主机名和IP
- 根据安全字符正则表达式验证IMAP文件夹名称；搜索查询长度有限
- 阻止电子邮件头注入：主题和回复_拒绝CR/LF
- SMTP速率限制可防止发送失控（默认为10/min）
- 删除操作移至回收站；
EXPUNGE从未被召唤 - 电子邮件正文截断为50000个字符以保护上下文窗口
- 附件二进制内容永远不会返回（仅元数据）
- UID字段已验证（仅限正整数；列表上限为1000）
看 安全.md 用于漏洞报告。
许可证
麻省理工学院