email-mcp

通过 Windows 版经典 Outlook 以原生 COM（pywin32）驱动电子邮件和日历。打包为一条 email 命令，它既是 CLI 又是 stdio MCP 服务器。无需 Azure 应用注册、无需 OAuth、无需 PowerShell —— 它只是驱动你已登录的 Outlook 桌面客户端。

要求

• Windows 10/11

• 经典 Outlook 桌面版，至少配置了一个账户

• Python 3.10+ 和 uv

Windows 版“新”Outlook 不暴露 COM。如果你使用的是新版 Outlook 且无法切回经典版，那么这对你不起作用。

只能通过 Outlook 桌面客户端访问 COM——没有单独的认证。工具所看到的就是已登录 Outlook 的账户，已发送邮件会像你手动发送一样落入真实的“已发送”文件夹中。

Related MCP server: outlook-classic-mcp

安装 / 运行

使用 uvx 直接从 GitHub 运行（无需克隆，无需手动安装）：

uvx --from git+https://github.com/kerodkibatu/email-mcp email --help

uv 会在首次运行时解析并缓存包；后续调用会很快。

CLI

每个工具都是 email 的子命令。输出为 stdout 上的 JSON。

# List configured Outlook accounts
uvx --from git+https://github.com/kerodkibatu/email-mcp email list-accounts

# Query across all mail folders with a MongoDB-style filter (JSON string)
uvx --from git+https://github.com/kerodkibatu/email-mcp email query \
  --filter '{"$and":[{"from":{"$contains":"@kyros.com"}},{"unread":true}]}' \
  --limit 20 --order-by received_desc

# Read one email by EntryID
uvx --from git+https://github.com/kerodkibatu/email-mcp email read --entry-id "0000000..."

# Send a new mail (account is REQUIRED — see below)
uvx --from git+https://github.com/kerodkibatu/email-mcp email send \
  --to client@example.com \
  --subject "Status update" \
  --body "Heads up — ..." \
  --account kerod@towlydigital.com

# Save a new mail as a draft instead of sending (same flags as send, no --send-as)
uvx --from git+https://github.com/kerodkibatu/email-mcp email draft \
  --to client@example.com \
  --subject "Status update" \
  --body "Heads up — ..." \
  --account kerod@towlydigital.com

MCP

email mcp 启动一个 stdio MCP 服务器，暴露全部 11 个工具。将其添加到你的 .mcp.json（或 claude_desktop_config.json）：

{
  "mcpServers": {
    "email": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/kerodkibatu/email-mcp", "email", "mcp"]
    }
  }
}

首次启动较慢，因为 uv 需要解析包；后续启动会命中缓存。

工具

选择发送账户

send_email、reply_email 和 forward_email 要求 提供 account 参数——它是所配置 Outlook 账户名（通常是 SMTP 地址）的子串。这是有意为之：当配置了多个账户（例如个人 + 工作）时，默认使用 Outlook 的主账户是一个陷阱——个人邮件会从工作账户泄露出去，反之亦然。强制调用者指定账户名称，使发送意图明确。

如果提供的 account 与任何已配置账户都不匹配（不区分大小写的子串匹配），工具将报错并列出可用账户。如果你还不知道账户名，请先运行 list_accounts。传输账户通过 SendUsingAccount 直接设置在 Outlook 项目上。

{
  "to": "client@example.com",
  "subject": "Status update",
  "body": "Heads up — ...",
  "account": "kerod@towlydigital.com"
}

Send As（实验性 — 需要 Exchange“Send As”权限）

实验性。 这仅通过 pywin32 COM 驱动经典 Outlook——没有 Azure/OAuth 路径。行为取决于租户策略，可能会退信、静默降级，或将邮件留在发件箱中。请将其视为尽力而为。

send_email、reply_email 和 forward_email 接受可选的 send_as 参数——一个用于作为其发送的 SMTP 地址。收件人会在发件人（From）中看到该地址，并且 不会 显示“代表（on behalf of）”提示。这是真正的 Exchange Send As，不同于代表发送（Send on Behalf）。

在机制上，该工具将 SendUsingAccount 设置为你提供的 account（传输邮箱），然后在 Exchange 中解析 send_as，并在提交前通过项目的 PropertyAccessor 覆盖 PR_SENT_REPRESENTING_* 和 PR_SENDER_* 这两组 MAPI 属性，使其指向该地址。覆盖发件人属性（而不仅仅是代表属性）正是将“代表（on behalf of）”化为纯粹 Send As 的关键。Exchange 会在提交时验证权限。

要求：

• account 用户必须在 send_as 邮箱上拥有 Send As 权限，该权限由 Exchange 管理员在服务端授予。该工具无法授予或检查此权限——它只能尝试发送。

• send_as 地址必须能被 Exchange 解析——通常是同一租户中的邮箱。外部地址（gmail.com 等）在解析时会报错失败。

• 如果缺少权限，行为取决于租户策略：Exchange 可能退信、将其静默降级为“代表（on behalf of）”，或将其留在发件箱中。

• 此功能仅在明确授权的 Exchange 组织内部有效。它不能被用来冒充外部发件人。

{
  "to": "client@example.com",
  "subject": "Status update",
  "body": "Heads up — ...",
  "account": "admin@custom.com",
  "send_as": "contact@custom.com"
}

当使用 send_as 时，响应会包含一个 sent_as 字段，用于回显该地址。

发送附件

send_email 接受一个可选的 attachments 数组，包含绝对文件路径。每个路径都必须存在并指向一个常规文件；如果任何路径无效，工具将返回错误并列出来违规项，且不会发送。Windows 上正斜杠和反斜杠均可接受；~ 和环境变量 不会 被展开——请传入完整解析后的路径。

{
  "to": "kerod@example.com",
  "subject": "Signed contract",
  "body": "See attached.",
  "account": "kerod@towlydigital.com",
  "attachments": [
    "C:\\Users\\Kerod\\Desktop\\contract.pdf",
    "C:/Users/Kerod/Desktop/cover-letter.pdf"
  ]
}

下载附件

download_attachments 工具从电子邮件中提取文件并保存到本地，返回绝对文件夹路径。

• 位置： 文件保存在用户的“下载”文件夹下：~/Downloads/email-attachments/YYYY-MM-DD_sender-slug_subject-slug/。

• 内嵌图片： 默认会过滤掉徽标和签名图片，以避免杂乱。如果你确实需要它们，请设置 include_inline: true。

• 幂等性： 对同一封电子邮件重新运行该工具会安全地复用文件夹（通过 .entry_id 标记跟踪），并在两封不同电子邮件生成相同 slug 名称时加以区分。

工作原理

email 命令通过 COM 附加到正在运行的 Outlook 实例（如果没有正在运行的实例，则回退到启动一个），然后驱动 MAPI 命名空间来读写邮件。所有 COM 访问都通过单个 Outlook 会话进行；该工具从不生成 PowerShell。

这意味着：

• Outlook 必须已安装（不需要打开——首次调用会启动它）

• 工具所看到的就是已登录 Outlook 的账户——没有单独的认证

• 已发送邮件会出现在用户的“已发送”文件夹中，就像他们手动发送一样

许可证

MIT — 参见 LICENSE。