AI导哈

多账户IMAP/SMTP服务器

IMAP MCP Server是一个多账户IMAP/SMTP服务器，通过单一部署连接多个电子邮件账户，专为Claude设计。

  • by AlobarQuest
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 AlobarQuest/imap-mcp-server

使用说明

IMAP MCP服务器

Claude的多帐户IMAP/SMTP MCP服务器。使用FastMCP通过单个部署连接多个电子邮件帐户。

设置

1.安装依赖项

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

2.配置帐户

cp .env.example .env
# Edit .env with your IMAP/SMTP credentials

每个帐户都通过编号的环境变量进行配置：

变量 必填 默认 描述
IMAP_ACCOUNT_N_NAME 是 工具调用中使用的短名称
IMAP_ACCOUNT_N_EMAIL 是 电子邮件地址
IMAP_ACCOUNT_N_IMAP_HOST 是 IMAP服务器主机名
IMAP_ACCOUNT_N_IMAP_PORT 没有 993 IMAP端口
IMAP_ACCOUNT_N_SMTP_HOST 是 SMTP服务器主机名
IMAP_ACCOUNT_N_SMTP_PORT 没有 587 SMTP端口
IMAP_ACCOUNT_N_SMTP_SECURITY 没有 starttls starttls （端口587）或 ssl （端口465）
IMAP_ACCOUNT_N_USERNAME 是 登录用户名
IMAP_ACCOUNT_N_PASSWORD 是 登录密码
IMAP_ACCOUNT_N_TRASH_FOLDER 没有 Trash 用于软删除的文件夹名称

通过递增N（1,2,3…）来添加所需数量的帐户。编号中的空白得到了妥善处理。

3.运行服务器

python -m src.server

默认情况下，从端口8000开始，使用可流式传输的http。

4.连接到克劳德桌面

在Claude Desktop设置中添加为远程MCP服务器：

https://imap-mcp.devonwatkins.com/mcp

或者为了当地发展：

{
  "mcpServers": {
    "imap": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

工具

工具 说明
imap_list_accounts 列出所有已配置的帐户及其连接状态
imap_list_emails 列出带有过滤器的电子邮件（文件夹、未读、日期、搜索）
imap_read_email 通过UID读取完整的电子邮件内容（使用PEEK，不标记为已读）
imap_search_emails 跨文件夹的全文搜索
imap_send_email 通过SMTP发送电子邮件（生成邮件ID）
imap_mark_read 将电子邮件标记为已读/未读
imap_move_email 在文件夹之间移动电子邮件
imap_list_folders 列出邮箱文件夹
imap_delete_email 删除电子邮件（软：移至垃圾箱或永久）

所有工具（除 imap_list_accounts)需要一个 account 与帐户匹配的参数 NAME.

健康终点

终点 目的
GET /health 状态与每个帐户的详细信息相结合
GET /health/live 活体探针（进程已结束）
GET /health/ready 准备就绪探测（至少有一个帐户可以进行身份验证）

就绪端点主动探测IMAP连接，它不依赖于缓存状态。

{"status": "ready", "accounts": {"adjustright": "connected", "watkinshomesales": "connected"}}

错误处理

所有工具都返回具有稳定代码的结构化错误：

{"error": true, "code": "AUTH_FAILED", "message": "...", "account": "adjustright"}

错误代码： AUTH_FAILED, CONNECTION_TIMEOUT, FOLDER_NOT_FOUND, EMAIL_NOT_FOUND, SEND_FAILED, ACCOUNT_NOT_FOUND

码头工人

docker build -t imap-mcp-server .
docker run -p 8000:8000 --env-file .env imap-mcp-server

Dockerfile包括 bws CLI用于在启动时通过以下方式从Bitwarden Secrets Manager获取密码 start.sh.

生产部署

作为Flavor a应用程序部署在Coolify上（单容器，源代码构建）。

  • 域名： https://imap-mcp.devonwatkins.com
  • 密码： 启动时从BWS获取(start.sh)
  • 健康检查： /health/live 在8000端口

测试

pip install pytest pytest-asyncio
python -m pytest tests/ -v

E2E测试

# Read-only tests against production
python scripts/test_live.py

# Include mark/move/delete tests (restores state after)
python scripts/test_live.py --destructive

# Include send test (sends email to self)
python scripts/test_live.py --send

# Full suite
python scripts/test_live.py --destructive --send

# Test a specific account
python scripts/test_live.py --account watkinshomesales

建筑

src/
  server.py     — FastMCP app, 9 tool definitions, health endpoints
  client.py     — Async IMAP (aioimaplib) and SMTP (aiosmtplib) clients
  accounts.py   — Account registry from IMAP_ACCOUNT_N_* env vars
  models.py     — Pydantic models for all request/response types
  errors.py     — Typed exceptions (AuthenticationError, FolderNotFoundError, etc.)
tests/          — 59 unit tests
scripts/        — E2E test suite and debug tools
start.sh        — Entrypoint that fetches BWS secrets before starting server

关键设计决策

  • 常规搜索，而非UID搜索： Namecheap私人电子邮件不支持UID搜索。我们使用常规的SEARCH搜索序列号，然后使用FETCH（UID）转换为稳定的UID。
  • 每个帐户异步。锁： 防止并发请求破坏IMAP文件夹选择状态。
  • 身体。偷看[]： 读取操作从不将电子邮件标记为已读。
  • 延迟连接： IMAP连接是在首次使用时建立的，而不是在启动时。就绪端点探测真实连接。

相关 MCP