Email Agent MCP

代理人电子邮件

](https://www.npmjs.com/package/email-agent-mcp) ](https://npmjs.org/package/email-agent-mcp)    ](https://github.com/UseJunior/email-agent-mcp/stargazers)   ](https://socket.dev/npm/package/email-agent-mcp) 

英语 | 西班牙语 | 简体中文 | 葡萄牙语（ 巴西） | 德语

电子邮件代理mcp 通过 UseJunior --AI代理的本地电子邮件连接。

Agent Email是一个开源的TypeScript MCP服务器，它允许Claude Code、Cursor、Gemini CLI、OpenClaw和其他兼容MCP的运行时读取电子邮件、搜索线程、起草回复、标记消息、更改读取状态、移动消息，并通过您自己的邮箱发送邮件。目前支持Microsoft 365/Outlook和Gmail。安全第一默认值意味着在您明确配置分配列表之前，代理无法发送电子邮件。

快速开始

npx -y email-agent-mcp

交互式设置向导将引导您完成OAuth配置和邮箱选择。

今天什么有效

• 通过MCP stdio访问Microsoft 365/Outlook邮箱
• list_emails, read_email, search_emails，以及 get_thread
• create_draft, update_draft, send_draft, send_email，以及 reply_to_email
• label_email, mark_read，以及 move_to_folder
• 发送分配列表、默认情况下禁用删除和清除错误

当前的启动准备过程已针对真实的Outlook邮箱进行了验证，用于读取、起草、发送、分类、移动和读取状态流。

为什么存在

人工智能代理需要阅读、回复电子邮件并对其采取行动，但电子邮件API很复杂。OAuth流、Graph delta查询、Gmail推送订阅、HTML到markdown转换、线程语义——每个提供者都有自己的怪癖。

Agent Email将这种复杂性封装到具有安全防护的确定性MCP工具中：

• 发送和接收控制代理可以联系谁的列表
• 默认情况下禁用删除（需要明确选择加入）
• 删除API密钥、文件路径和堆栈跟踪的错误清理
• 具有路径遍历保护的主体文件沙盒

与Claude Code一起使用

添加 ~/.claude/settings.json 或你的项目 .claude/settings.json:

{
  "mcpServers": {
    "email-agent-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "email-agent-mcp"]
    }
  }
}

与光标一起使用

// .cursor/mcp.json
{
  "mcpServers": {
    "email-agent-mcp": {
      "command": "npx",
      "args": ["-y", "email-agent-mcp"]
    }
  }
}

与Gemini CLI一起使用

gemini extensions install https://github.com/UseJunior/email-agent-mcp

与OpenClaw一起使用

添加一个 mcp 阻止 ~/.openclaw/openclaw.json:

{
  // ... existing config ...
  mcp: {
    servers: {
      email: {
        command: "npx",
        args: ["tsx", "/path/to/email-agent-mcp/packages/email-mcp/src/serve-entry.ts"],
        transport: "stdio"
      }
    }
  }
}

版本说明：The mcp config键要求OpenClaw应用程序>=2026.3.24。如果CLI比应用程序旧，即使网关接受此密钥，它也可能在验证过程中拒绝此密钥。用以下命令更新CLI npm install openclaw@latest 在NemoClaw目录中，或直接使用以下命令重新启动网关 launchctl kickstart -k gui/501/ai.openclaw.gateway.

电子邮件监视器

当新电子邮件到达时，观察者会轮询您的邮箱并向OpenClaw发送唤醒信号：

# Set the hooks token (must match hooks.token in openclaw.json)
export OPENCLAW_HOOKS_TOKEN="your-hooks-token"

# Start the watcher (defaults to http://localhost:18789/hooks/wake)
npm run dev:watch

监视程序需要至少一个已配置的邮箱。跑 npx email-agent-mcp 或 npm run dev:configure 首先完成OAuth流程。

发射准备烟雾测试

在录制演示之前，请对真实邮箱和安全发送分配列表运行实时烟雾脚本。脚本练习：

• get_mailbox_status
• list_emails + read_email
• mark_read 未读->已读->未读
• label_email 关于一个安全的收件箱候选人
• create_draft
• 仅限草稿 reply_to_email
• 可选的 send_email

例子：

EMAIL_AGENT_MCP_HOME=/tmp/email-agent-mcp-live \
AGENT_EMAIL_SEND_ALLOWLIST=/tmp/email-agent-mcp-live/send-allowlist.json \
npm run launch:prep:smoke -- --live-write --send-to beta@usejunior.com

默认安全候选人选择查找 notifications@github.com 在收件箱中，这样您就可以在公共安全邮件而不是客户邮件上排练录制流程。 如果您的邮箱状态名称不是电子邮件地址，请传递 --reply-sender 或设置 EMAIL_AGENT_MCP_REPLY_SENDER 因此，脚本可以找到一条自我发送的消息，用于草稿回复检查。

工具参考

代理电子邮件公开了15个MCP工具：

出站附件

send_email, reply_to_email, create_draft，以及 update_draft 接受a 可选的 attachments 阵列。每个条目都有一个沙盒文件 path （读 相对于 EMAIL_MCP_SAFE_DIR，默认进程工作目录）或 内联 base64，加上可选 filename / mimeType 覆盖：

{
  "to": "alice@example.com",
  "subject": "Signed agreement",
  "body": "Attached as requested.",
  "attachments": [
    { "path": "./out/agreement.pdf" },
    { "base64": "iVBORw0KGgo...", "filename": "screenshot.png" }
  ]
}

每个文件的大小限制为25MB；Microsoft Graph还限制了内联发送 总计约3MB（较大的文件需要上传会话，目前尚不支持）。对于 update_draft，省略 attachments 保留草案的现有文件； 传递一个数组（即使是空的）会替换它们。

提供商支持

使用 email-agent-mcp configure --provider gmail 运行本地浏览器OAuth流，或在下添加手动邮箱令牌文件 ~/.email-agent-mcp/tokens/。参见 软件包/提供商gmail/README.md.

安全默认值

Agent Email附带了限制性默认值，您可以根据需要放宽这些默认值：

• 发送满列表：默认为空--在添加收件人之前，代理无法发送电子邮件
• 接收全部列表：默认情况下接受全部--控制哪些发件人触发观察者
• 删除已禁用：默认情况下，代理无法删除电子邮件。必须同时满足两个条件：

1. 操作员设置 AGENT_EMAIL_DELETE_ENABLED=true 在电子邮件代理mcp过程环境中（和 AGENT_EMAIL_HARD_DELETE_ENABLED=true 永久删除）。更改后需要重新启动。 1. 来电者经过 user_explicitly_requested_deletion: true 在工具调用中。

• 错误清理：API密钥、文件路径和堆栈跟踪都是从错误响应中编辑的
• 正文文件沙盒：没有 ../ 遍历、无符号链接、二进制检测

包装

质量和信任信号

• CI在每次pull请求和push到main时运行（lint、typecheck、Node 20+22上的测试）
• CodeQL和Semgrep安全扫描
• 向Codecov发布报道
• 通过以下方式执行OpenSpec可追溯性 npm run check:spec-coverage
• 整个套件中有300多个测试
• 维护人员： Steven Obiajulu 的

建筑

email-agent-mcp/
├── packages/
│   ├── email-core          Core actions, content engine, security
│   ├── email-mcp           MCP server adapter, CLI, watcher
│   ├── provider-microsoft  Microsoft Graph provider
│   ├── provider-gmail      Gmail API provider
│   └── email-agent-mcp         Distribution wrapper (npx entry point)
├── openspec/               Spec-driven development
└── scripts/                CI and validation scripts

释放

通过GitHub Actions使用npm OIDC可信发布进行标签驱动发布。所有5个包都按照依赖顺序发布 --provenance那么 server.json 发布到MCP官方注册表 mcp-publisher.

常见问题

这适用于Claude Code吗？

对。跑 npx email-agent-mcp 要启动MCP服务器，请在Claude Code设置中对其进行配置。

代理人可以在未经我许可的情况下发送电子邮件吗？

否。默认情况下，发送分配列表为空。在您明确配置允许的收件人之前，代理无法发送任何电子邮件。

这会存储我的电子邮件凭据吗？

OAuth令牌由Microsoft管理，并存储在您的操作系统密钥链或本地配置文件中 ~/.email-agent-mcp/.Agent Email从不存储原始密码。

我可以连接多个邮箱吗？

对。您可以同时配置Microsoft 365和Gmail。读取操作默认为您的主邮箱；当配置了多个邮箱时，写入操作需要指定一个邮箱。

OpenClaw CLI使用“无法识别的键：mcp”拒绝我的配置

OpenClaw CLI和macOS应用程序可以是不同的版本。运行网关的应用程序可能支持CLI尚未识别的配置键。更新CLI： cd ~/Projects/NemoClaw && npm install openclaw@latest或者，直接重启网关： launchctl kickstart -k gui/501/ai.openclaw.gateway.

监视器启动，但未找到任何邮箱

邮箱凭据存储在 ~/.email-agent-mcp/tokens/。如果此目录为空，请运行 npx email-agent-mcp 或 npm run dev:configure 通过OAuth进行身份验证。在至少配置一个邮箱之前，观察程序将退出，没有邮箱可供轮询。

OpenClaw说“演示模式——运行电子邮件代理mcp-configure进行连接”

MCP服务器正在运行，但没有真正的邮箱凭据。跑 npx email-agent-mcp 要完成交互式OAuth设置，请重新启动OpenClaw网关，以便MCP服务器使用有效令牌重新连接。

尽管我刚刚通过身份验证，但令牌在一周后过期

Microsoft刷新令牌通常持续90天，但您的Azure AD租户可能会强制缩短生存期。该代码使用带有操作系统密钥链持久性的SOAP(@azure/identity-cache-persistence)，自动处理静默令牌刷新。如果SST报告 interaction_required 或 invalid_grant，重新运行 npx email-agent-mcp 重新验证。常见原因：条件访问策略、MFA重新验证要求或管理员配置的令牌生命周期策略。

OpenClaw Telegram机器人收到消息但没有响应

使用验证Telegram频道是否正常 openclaw status。如果频道显示OK但没有返回响应，请检查：（1）您的Telegram用户ID是否在 channels.telegram.allowFrom 在 openclaw.json，（2）存在匹配的绑定 channel: "telegram"，以及（3）网关在配置更改后重新启动。对于一个所有者机器人，使用 dmPolicy: "allowlist" 明确 allowFrom ID，而不是依赖配对批准。

发展

npm ci
npm run build
npm run lint --workspaces --if-present
npm run test:run
npm run check:spec-coverage

另见

• 安全DOCX套件 --使用编码代理对Word文档进行外科编辑
• 开放协议 --使用编码代理填写标准法律模板

隐私

代理电子邮件完全在您的本地计算机上运行。电子邮件凭据存储在您的操作系统钥匙链（SCL）和本地配置文件中。代理电子邮件本身不会将电子邮件内容发送到外部服务器。

治理

• 贡献指南
• 行为准则
• 安全策略
• 更新日志