邮寄imap-mcp-rs
默认情况下，用于通过stdio访问IMAP电子邮件的安全、高效的模型上下文协议（MCP）服务器，具有可选的流式HTTP传输。在IMAP邮箱上提供读/写操作，具有结构化输出、基于光标的分页和安全优先的设计。
特性
- 缺省安全：仅TLS连接，密码机密从未记录或返回
- 结构化输出：具有摘要和元数据的一致工具响应信封
- 基于光标的分页：跨大型邮箱高效搜索邮件
- 消息解析：提取文本、HTML、页眉和附件并进行净化
- 多账户支持：通过环境变量配置多个IMAP帐户
- PDF文本提取：从PDF附件中提取可选文本
- 铁锈供电：使用tokio实现快速、内存安全的异步/等待
- 写入操作：邮件突变和邮箱管理需要明确启用
安装
根据您的环境和偏好选择安装方法。
使用NPX（推荐）
最简单的方法-无需全局安装。
npx @bradsjm/mail-imap-mcp-rs@latest可选HTTP传输示例：
npx @bradsjm/mail-imap-mcp-rs@latest --transport http支持的npm/原生目标：
- macOS：苹果硅(
aarch64-apple-darwin)，英特尔(x86_64-apple-darwin) - Linux
arm64：glibc(aarch64-unknown-linux-gnu) - Linux x64：glibc(
x86_64-unknown-linux-gnu)，薄纱/阿尔卑斯(x86_64-unknown-linux-musl) - Windows x64：MSVC(
x86_64-pc-windows-msvc)
或全局安装：
npm install -g @bradsjm/mail-imap-mcp-rs
mail-imap-mcp-rs使用Curl安装程序（Linux/macOS）
直接从GitHub release安装固定版本：
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/bradsjm/mail-imap-mcp-rs/releases/download/v0.1.0/mail-imap-mcp-rs-installer.sh | sh更安全的替代方案（下载、检查，然后运行）：
curl --proto '=https' --tlsv1.2 -LsSf -o mail-imap-mcp-rs-installer.sh https://github.com/bradsjm/mail-imap-mcp-rs/releases/download/v0.1.0/mail-imap-mcp-rs-installer.sh
sh mail-imap-mcp-rs-installer.sh使用Docker
从GHCR中提取预构建的多拱形图像：
docker pull ghcr.io/bradsjm/mail-imap-mcp-rs:latest
docker run --rm -i --env-file .env ghcr.io/bradsjm/mail-imap-mcp-rs:latest可选HTTP传输示例：
docker run --rm -p 127.0.0.1:8000:8000 --env-file .env ghcr.io/bradsjm/mail-imap-mcp-rs:latest --transport http本地构建：
docker build -t mail-imap-mcp-rs .
docker run --rm -i --env-file .env mail-imap-mcp-rs来自源头
cargo install --path .二进制文件可在 $HOME/.cargo/mail-imap-mcp-rs.
运输方式
服务器默认为 stdio，这是大多数MCP桌面集成的正确模式。
仅当您明确需要时才使用流式HTTP：
mail-imap-mcp-rs --transport http可选绑定控件：
mail-imap-mcp-rs --transport http --http-bind-address 127.0.0.1 --http-port 8000HTTP模式为MCP提供服务 http://127.0.0.1:8000/mcp 默认情况下。
安全说明：
- HTTP传输默认仅为localhost。
- 服务器不添加内置的HTTP身份验证或TLS终止。
- 不要让此服务器公开访问，除非暴露是故意的，并受到可信边界（如反向代理、防火墙或专用网络）的保护。
快速开始
配置MCP
使用此MCP配置示例并添加您的凭据：
{
"mcpServers": {
"server-name": {
"command": "npx",
"args": ["-y", "@bradsjm/mail-imap-mcp-rs@latest"],
"env": {
"MAIL_IMAP_DEFAULT_HOST": "imap.gmail.com",
"MAIL_IMAP_DEFAULT_USER": "your-email@gmail.com",
"MAIL_IMAP_DEFAULT_PASS": "your-app-password"
}
}
}
}# Optional: defaults shown
MAIL_IMAP_DEFAULT_PORT=993
MAIL_IMAP_DEFAULT_SECURE=true重要提示： 使用特定于应用程序的密码，而不是您的帐户密码。有关生成应用程序密码的信息，请参阅电子邮件提供商的文档。
启用写入操作
默认情况下，写操作（邮件突变和邮箱管理）被禁用.显式启用：
MAIL_IMAP_WRITE_ENABLED=true多个帐户
# Default account
MAIL_IMAP_DEFAULT_HOST=imap.gmail.com
MAIL_IMAP_DEFAULT_USER=user@gmail.com
MAIL_IMAP_DEFAULT_PASS=app-password
# Work account
MAIL_IMAP_WORK_HOST=outlook.office365.com
MAIL_IMAP_WORK_USER=user@company.com
MAIL_IMAP_WORK_PASS=work-password
# Personal account
MAIL_IMAP_PERSONAL_HOST=imap.fastmail.com
MAIL_IMAP_PERSONAL_USER=user@fastmail.com
MAIL_IMAP_PERSONAL_PASS=personal-password高级配置
有关超时、光标设置、读取会话缓存调整和其他高级选项，请参阅 高级配置.
要信任私有或自签名的IMAP服务器证书而不禁用TLS验证，请设置：
MAIL_IMAP_CA_CERT_PATH=/path/to/ca-certificates.pem工具参考
所有工具都返回一个一致的信封：
{
"summary": "Human-readable outcome",
"data": { /* tool-specific data */ },
"meta": {
"now_utc": "2024-02-26T10:30:45.123Z",
"duration_ms": 245
}
}读取操作
| 工具 | 目的 |
|---|---|
imap_list_accounts | 列出已配置的帐户，但不公开凭据 |
imap_list_mailboxes | 列出所有可见的邮箱/文件夹 |
imap_search_messages | 使用基于光标的分页进行搜索 |
imap_get_message | 获取解析后的消息详细信息 |
imap_get_message_raw | 获取RFC822源代码以进行诊断 |
写入操作
| 工具 | 目的 |
|---|---|
imap_apply_to_messages | 执行一个操作(move, copy, delete)明确的信息 |
imap_update_message_flags | 添加、删除或替换显式消息上的标志 |
imap_manage_mailbox | 创建、重命名或删除邮箱 |
imap_get_operation | 轮询写入操作状态，并可选择获取其终端结果 |
imap_cancel_operation | 请求取消正在运行的写入操作 |
写入操作需要 MAIL_IMAP_WRITE_ENABLED=true.
有关完整的工具契约、输入/输出模式和验证规则，请参阅 工具合同.
故障排除
连接超时
Error: operation timed out: tcp connect timeout增加 MAIL_IMAP_CONNECT_TIMEOUT_MS （默认值：30000毫秒）。看 高级配置.
认证失败
Error: authentication failed: [AUTHENTICATIONFAILED] Authentication failed.- 验证用户名和密码是否正确
- 为Gmail/Outlook使用特定于应用程序的密码（不是帐户密码）
- 支票帐户允许IMAP访问
写入操作已禁用
Error: invalid input: write tools are disabled; set MAIL_IMAP_WRITE_ENABLED=true集 MAIL_IMAP_WRITE_ENABLED=true 以启用消息突变和邮箱管理操作。
光标无效/已过期
Error: invalid input: cursor is invalid or expired在没有光标的情况下重新运行搜索。看 光标分页 了解详情。
搜索范围太广
Error: invalid input: search matched 25000 messages; narrow filters to at most 1000 results添加更紧密的过滤器(last_days, from, subject，日期范围）并重新运行。
邮箱快照已更改
Error: conflict: mailbox snapshot changed; rerun search邮箱的 UIDVALIDITY 改变。重新运行搜索。看 消息ID格式.
安全
有关全面的安全文档，请参阅 安全考虑.
关键安全功能：
- TLS强制：不安全的连接被拒绝
- 本地HTTP默认值：可选的HTTP传输绑定到localhost，除非您覆盖它
- 密码保密：密码从未记录或返回
- 有界输出：正文、HTML、附件截断到极限
- 写控制：破坏性行动需要明确的选择加入
- HTML净化：使用对HTML进行净化
ammonia
文档
许可证
MIT许可证-请参阅 许可证 文件以获取详细信息。
贡献
欢迎投稿！在提交之前，确保代码已格式化、过梁和测试。