AI导哈

邮件管理服务

一个为macOS Mail提供本地MCP服务器的服务，支持读取未发送的草稿、回复和转发邮件，以及有限的邮件移动功能。

  • by atfinke
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 atfinke/mail-mcp

使用说明

邮件MCP

macOS Mail的本地MCP服务器读取，以及可见的未发送的撰写、回复和转发草稿，以及受限制的单消息移动。

完全由OpenAI GPT-5.4通过Codex构建。

概述

此项目通过MCP公开Apple Mail帐户、邮箱、收件箱消息和直接消息读取。

支持的工具：

  • mail_check_access
  • mail_list_accounts
  • mail_list_mailboxes
  • mail_list_mailbox_messages
  • mail_list_inbox_messages
  • mail_get_message
  • mail_compose_message
  • mail_reply_to_message
  • mail_forward_message
  • mail_move_message

主要的读取工作流程是 mail_list_inbox_messages，它返回所有收件箱的消息并支持 headersOnly: true 当您只需要标头和元数据时。

撰写工作流是有意缩小的：服务器可以打开可见的未发送的撰写、回复和转发草稿，但它不公开任何发送工具。 移动工作流受到有意限制：它支持在同一帐户内移动一封邮件，但不允许移动到垃圾箱或已删除的邮件邮箱。

路径约定

  • 工具输入使用显式分段数组：
    • mailboxPathSegments: ["Inbox"]
    • mailboxPathSegments: ["Archive", "2026"]
    • destinationMailboxPathSegments: ["Receipts"]
  • 邮箱结果包括两者 path 和 pathSegments.使用 path 用于显示和 pathSegments 调用工具时。
  • 消息结果包括两者 mailboxPath 和 mailboxPathSegments.使用 mailboxPath 用于显示和 mailboxPathSegments 调用工具时。
  • 消息结果使用 id对特定消息进行操作的工具需要在输入名称下使用相同的值 messageId.

往返示例：

  1. 呼叫 mail_list_mailboxes 并选择邮箱结果，例如：

    {
  "accountId": "account-1",
  "name": "Receipts",
  "path": "Archive / 2026 / Receipts",
  "pathSegments": ["Archive", "2026", "Receipts"]
}

  2. 呼叫 mail_list_mailbox_messages 与：

    {
  "accountId": "account-1",
  "mailboxPathSegments": ["Archive", "2026", "Receipts"]
}

  3. 取一个返回的消息对象，例如：

    {
  "id": 4812,
  "accountId": "account-1",
  "mailboxPath": "Archive / 2026 / Receipts",
  "mailboxPathSegments": ["Archive", "2026", "Receipts"]
}

  4. 呼叫 mail_get_message 与：

    {
  "accountId": "account-1",
  "mailboxPathSegments": ["Archive", "2026", "Receipts"],
  "messageId": 4812
}

需求

  • Node.js 20+
  • macOS
  • Mail.app已配置至少一个帐户
  • 控制邮件的自动化权限
  • A签名 MailMCPHelperApp 构建

设置

  1. 安装依赖项：

    npm install

  2. 复制 .env.example 到 .env 如果要覆盖默认值：

    cp .env.example .env

  3. 构建助手应用程序：

    npm run build:helper-app

    构建脚本编译未签名的应用程序，然后用第一个本地包对完成的捆绑包进行签名 Apple Development 身份。用以下内容覆盖该选择 MAIL_MCP_CODESIGN_IDENTITY 如果需要的话。

  4. 进行本地质量检查：

    npm run verify

  5. 运行一个真正的邮件烟雾测试：

    npm run test:live

可选环境变量：

  • MAIL_MCP_REQUEST_TIMEOUT_MS
  • MAIL_MCP_HELPER_TIMEOUT_MS
  • MAIL_MCP_HELPER_APP_PATH

跑

启动开发中的服务器：

npm run dev

构建生产输出：

npm run build
npm start

权限

服务器启动已签名的 MailMCPHelperApp 并在该应用程序流程中运行邮件自动化。这将使macOS自动化/TCC边界连接到助手应用程序，而不是终端或客户端进程。

跑 mail_check_access 安装后一次。首次使用时，macOS可能会提示用户允许控制邮件。

如果提示没有自动出现在您的客户端中，请直接启动助手应用程序一次：

open MailMCPHelperApp/build/Build/Products/Release/MailMCPHelperApp.app

服务器甚至在授予访问权限之前就已启动。使用 mail_check_access 以确认权限状态，并在macOS Automation同意仍悬而未决的情况下收到可操作的错误消息。

若要在测试计算机上重新运行同意流，请重置助手应用程序的Mail Apple Events权限，然后运行 mail_check_access 再一次：

tccutil reset AppleEvents com.andrewfinke.mailmcphelper

重置后，确认macOS提示符名称 MailMCPHelperApp，然后确认显示“系统设置” MailMCPHelperApp -> Mail.

验证

npm run verify

备注

  • 支持的文件系统 ~/Library/Mail 这里故意不使用这种方法，因为它需要更广泛的隐私访问，并且依赖于未记录的邮件存储细节。
  • 收件箱和邮箱列表工具将返回邮件正文，除非 headersOnly: true 已设置。
  • 撰写、回复和转发工具始终打开可见的草稿。有意避免隐藏草稿模式，因为Mail不能通过自动化可靠地清理不可见的组合对象。
  • 原始标题对于列表工具是可选的，默认为 false.
  • 包括附件元数据，但不包括附件字节。
  • 助手应用程序通过进程内执行JavaScript以实现自动化 OSAKit.

MCP设置

服务器通过stdio运行。

构建服务器的客户端配置示例：

{
  "mcpServers": {
    "mail": {
      "command": "node",
      "args": ["/absolute/path/to/mail-mcp/dist/index.js"],
      "cwd": "/absolute/path/to/mail-mcp",
      "env": {
        "MAIL_MCP_HELPER_APP_PATH": "/absolute/path/to/mail-mcp/MailMCPHelperApp/build/Build/Products/Release/MailMCPHelperApp.app"
      }
    }
  }
}

对于不先建设的地方发展：

{
  "mcpServers": {
    "mail": {
      "command": "npx",
      "args": ["tsx", "src/index.ts"],
      "cwd": "/absolute/path/to/mail-mcp"
    }
  }
}

相关 MCP