stalwart-mail-mcp

Stalwart Mail MCP

捷克语

一个 MCP 服务，可让 Claude Desktop（或任何使用 stdio 通信的 MCP 客户端）处理你自己的 Stalwart 邮件服务器中的邮箱：搜索和阅读邮件（包括附件和扫描件）、在邮件线程中回复、发送邮件、保存草稿，以及查找或添加联系人。

它使用邮箱自身的凭据通过 JMAP 通信。无需在服务器上安装任何内容。

Claude Desktop ──stdio──▶ dist/index.cjs (Node, this MCP server)
                              │  HTTPS · JMAP (RFC 8620 / 8621 / 9610)
                              ▼
                 https://mail.example.com/jmap   (reverse proxy → Stalwart)

它还支持远程模式：在 Stalwart 旁边运行同一个服务，并将其作为自定义连接器添加到 Claude，这样就能在 claude.ai、移动应用和所有桌面聊天中使用邮箱——用户通过 Stalwart 自带的 OAuth 登录，服务不保存任何凭据。详见 docs/remote.md。

docs/small-infrastructure.md介绍了它如何融入小型可自托管环境——反向代理、需要开放的服务、共享邮箱，以及为家庭或团队打造品牌版本。

工具

工具名称带有前缀，默认为 mail_（品牌版本可以更改前缀）。

工具	功能
mail_list_mailboxes	邮箱账户（个人和共享）、带邮件数量的文件夹、允许的发件人、通讯录
mail_search_emails	全文搜索／按发件人／收件人／主题／文件夹／日期／未读／有附件搜索，或搜索整个邮件线程
mail_get_email	按 ID 获取完整邮件（将 HTML 转为文本），并附带带编号的附件列表
mail_get_attachment	获取附件内容：文本、逐页 PDF、扫描件和拍摄文档的 OCR、图像；并将文件保存到磁盘
mail_send_email	发送新邮件或回复（in_reply_to_id、reply_all），可添加磁盘中的附件
mail_create_draft	功能相同，但只保存到草稿箱
mail_send_draft / mail_delete_draft	按 ID 发送／删除草稿
mail_search_contacts	所有账户的通讯录，以及邮件历史中的发件人和收件人
mail_add_contact	添加联系人（个人或共享通讯录）

邮件发送会立即执行且无法撤销，因此工具说明会要求模型仅在用户明确指示时发送，否则创建草稿。

安装

Claude Desktop（扩展）

从最新版本下载 stalwart-mail.mcpb 并打开，Claude Desktop 会提示安装。也可以自行构建：

npm install
./pack.sh                  # → stalwart-mail.mcpb
open stalwart-mail.mcpb    # Claude Desktop → Install

填写服务器地址、邮箱地址和密码。可选：设置语言和用于 OCR 的 Mistral API 密钥。密码会保存在操作系统的钥匙串中。

任意 MCP 客户端（stdio）

该服务已发布到 npm，包名为 stalwart-mail-mcp，并已收录到 MCP Registry，标识为 io.github.cybersmurf/stalwart-mail-mcp，因此无需检出代码：

{
  "mcpServers": {
    "stalwart-mail": {
      "command": "npx",
      "args": ["-y", "stalwart-mail-mcp"],
      "env": {
        "STALWART_URL": "https://mail.example.com",
        "STALWART_USER": "[email protected]",
        "STALWART_PASSWORD": "…"
      }
    }
  }
}

Claude Code：claude mcp add stalwart-mail --env STALWART_URL=https://mail.example.com --env [email protected] --env STALWART_PASSWORD=… -- npx -y stalwart-mail-mcp

网页版 Claude、桌面聊天和手机

在 Stalwart 旁边运行服务（stalwart-mail-mcp --http 或使用 Docker 镜像），并将其 URL 添加为自定义连接器——docs/remote.md中提供了逐步说明。

配置

变量	含义
STALWART_URL	服务的公开地址，例如 https://mail.example.com（必填）
STALWART_USER	登录所用的邮箱（必填）
STALWART_PASSWORD	邮箱密码或应用密码——以 Basic 身份验证方式发送
STALWART_TOKEN	用于替代密码的 OAuth 访问令牌——以 Bearer 身份验证方式发送
MAIL_LANG	auto（默认：使用机器语言；不支持时使用英语）或区域设置代码
MAIL_TOOL_PREFIX	工具名称的前缀，默认为 mail
MAIL_BRAND	服务的显示名称，默认为 Stalwart Mail
MAIL_DOWNLOAD_DIR	附件的保存位置，默认为 ~/Downloads/Mail-Attachments
MAIL_TIMEZONE	输出中日期使用的 IANA 时区，默认为机器的时区
MAIL_OCR_PROVIDER、MAIL_OCR_API_KEY、MAIL_OCR_MODEL、MAIL_OCR_BASE_URL	负责读取扫描件的服务——参见 OCR 提供商
MISTRAL_API_KEY	快捷设置：只设置此项时，扫描件会发送到 Mistral OCR
MAIL_ALLOW_SEND	false 会移除 send_email 和 send_draft
MAIL_ALLOW_DRAFTS	false 会移除 create_draft 和 delete_draft
MAIL_ALLOW_CONTACT_EDIT	false 会移除 add_contact
MAIL_ALLOW_ATTACHMENTS	false 会移除 get_attachment
MAIL_SAVE_ATTACHMENTS	false = 打开的附件只会被读取，不会写入磁盘

它可以执行的操作

每项功能都是扩展设置（或上述环境变量）中的一个开关，默认全部开启。关闭的功能根本不会作为工具提供，因此无论客户端记住了什么审批提示，都不影响这一点：

• 关闭发送功能 → Claude 可以读取邮箱并撰写草稿，但绝不会从该邮箱发送邮件；
• 关闭发送、草稿和联系人编辑功能 → 邮箱为只读；
• 关闭附件保存功能 → get_attachment 会从临时副本读取文件，并标记为只读；开启保存功能时，它会将文件写入下载文件夹，并标记为写入工具，客户端在请求审批时可能会区别对待。

审批本身（“允许一次 / 始终允许”）由客户端负责，而非此服务。在 Claude Desktop 中，可在扩展设置中为每个工具设置审批；如果更新更改了工具定义，客户端可能会再次询问。

附件和 OCR

mail_get_attachment 会下载文件并返回模型可读取的内容：

• 文本文件以文本形式返回，HTML 会转换为文本；
• PDF 按页以文本形式返回（长 PDF 可使用 page_from / page_to）；
• 没有文本层的 PDF 页面（扫描件）和照片会发送到你选择的 OCR 提供商——结果为包含表格的 Markdown，这些页面会标记为 (OCR)。混合 PDF 只会发送扫描页面；
• 图片以图片形式返回；文件大小超过约 600 kB 或为 HEIC 格式时，会在 macOS 上缩小尺寸（sips）；
• 其他类型（docx、xlsx、zip 等）只会保存，并返回文件路径。

如果未设置提供商，或使用 ocr: false，扫描件会以第 1 页的图片形式返回（macOS），并附带说明。OCR 是此服务中唯一会将内容发送到邮件服务以外的位置的功能——内容会发送到你选择的提供商；若使用本地模型，则不会发送到任何地方。

OCR 服务提供方

MAIL_OCR_PROVIDER	说明	需要	读取 PDF
auto（默认）	设置了 MISTRAL_API_KEY 时使用 Mistral；设置了地址和模型时使用自定义服务；否则关闭	—	—
mistral	Mistral OCR（mistral-ocr-latest）	密钥	直接读取
anthropic	通过官方 SDK 使用 Claude（默认模型为 claude-opus-5-5）	密钥	直接读取
openai、openrouter、gemini	托管的 OpenAI 兼容视觉聊天 API	密钥 + 模型	页面图像
ollama、lmstudio	localhost 上的本地模型	模型	页面图像
custom	其他任何 OpenAI 兼容服务	MAIL_OCR_BASE_URL + 模型	页面图像
off	不进行 OCR	—	—

MAIL_OCR_API_KEY、MAIL_OCR_MODEL 和 MAIL_OCR_BASE_URL 用于补充配置。示例：

MAIL_OCR_PROVIDER=ollama      MAIL_OCR_MODEL=llama3.2-vision                         # fully local
MAIL_OCR_PROVIDER=openrouter  MAIL_OCR_API_KEY=…  MAIL_OCR_MODEL=<a vision model>
MAIL_OCR_PROVIDER=anthropic   MAIL_OCR_API_KEY=…
MAIL_OCR_PROVIDER=custom      MAIL_OCR_BASE_URL=http://nas.lan:8000/v1  MAIL_OCR_MODEL=…

仅接受图像的服务会收到从 PDF 中提取的每个扫描页 PNG 图像（即扫描页面本身，缩放至 2000 px）。无法将不完全由单张图片构成的页面交给这些服务，该页面会被报告为无法读取；Mistral 和 Anthropic 可以读取任何 PDF。每次发送三个页面。

注意事项：本地模型处理每个内容密集页面可能需要一分钟甚至更久，可能超出客户端的工具超时限制，因此请按页码范围读取长扫描文档。通用视觉模型的转录效果不错，但和所有 OCR 一样，可能会错置含图表的表格单元格；preview: true 会附加页面图像，供模型核对。使用 anthropic 时，如果请求被拒绝，服务端会使用备用模型重试（fallbacks: "default"），当前 Claude 模型均适用。

运行 node test/live-ocr.mjs，即可对扫描样例文件（或你自己的文件）使用环境中配置的服务提供方，并输出结果。

语言

工具标题、说明、输出和错误消息均已本地化。英文为源语言，捷克语由人工编写，德语、西班牙语、法语、意大利语、荷兰语、波兰语、葡萄牙语和斯洛伐克语均为机器翻译，尚未经过母语人士审阅，欢迎提出修正建议。

要添加或修正语言，请编辑 src/locales/<code>.ts（复制 en.ts，并保留 {placeholders} 和换行符），然后在 src/locales/index.ts 中注册。语言包可以不完整；缺失的键会回退到英文。npm run test:offline 会检查每个语言包是否与英文键一致。

品牌化构建（预设）

对于家庭或团队，你可以发布一个扩展，其中已预填服务地址，用户只需输入电子邮件和密码。预设是一个包含独立 manifest.json（以及可选的 icon.png）的文件夹；参见 presets/example。

./pack.sh --preset /path/to/preset     # → /path/to/preset/<name>.mcpb

预设的 manifest 通过 env 设置 MAIL_TOOL_PREFIX、MAIL_BRAND、MAIL_LANG 或 MAIL_DOWNLOAD_DIR，并为 server_url 提供默认值。请保持预设的 name 不变，这样 Claude Desktop 才会将新构建视为更新。

测试

npm run test:offline       # no mailbox needed: fake JMAP + fake OCR, the real server over stdio
MISTRAL_API_KEY=… node test/offline.mjs --live-ocr    # also sends the fixtures to the real OCR
STALWART_URL=… STALWART_USER=… STALWART_PASSWORD=… node test/smoke.mjs          # real mailbox
STALWART_URL=… STALWART_USER=… STALWART_PASSWORD=… node test/smoke.mjs --send   # also sends a mail to yourself

离线测试会检查附件、OCR、工具前缀、语言选择和语言包一致性。冒烟测试会创建并删除草稿；使用 --send 时，会在邮箱中留下一封测试邮件。

须知

• 密码错误会导致 Stalwart 在几次尝试后封禁 IP。 服务会在第一次调用工具时登录，而非启动时，因此重启客户端不会导致封禁；反复使用错误密码调用工具则会导致封禁。
• 专为 Stalwart 0.16 构建并在其上使用。邮件部分采用标准 RFC 8620/8621，可能适用于其他 JMAP 服务，但尚未经过测试；联系人功能需要支持 Contacts 的 JMAP（RFC 9610）。
• Stalwart 会拒绝 "inMailbox": null 的 Email/query 请求——必须省略该筛选条件，或为其提供一个 ID。
• 扩展包是一个 CommonJS 文件（约 3.8 MB，其中大部分是来自 unpdf 的 pdf.js）；.cjs 扩展名很重要，因为 package.json 声明了 "type": "module"。
• Claude Desktop 中的工具结果上限约为 1 MB，因此内联图像的限制为 600 kB。

许可证

MIT