SendGrid Secure

sendgrid-mcp-secure

一款安全优先的 SendGrid v3 API MCP 服务。

邮件发送不可撤销，还会影响发件人声誉。2025 年，一个恶意 MCP 程序包（postmark-mcp）会偷偷将其发送的每封邮件密送给攻击者。 本服务旨在从结构上杜绝这类事件及其变种，而不是仅依赖策略防范。

安全模型

1. 两阶段发送。 没有直接发送工具。preview_email 会验证并渲染确切的负载，返回供检查，并生成一次性确认令牌（10 分钟后过期）。send_email 只接受该令牌，并且只发送预览过的负载。完整渲染后的邮件总会先经过对话，然后才会发出。
2. 默认试运行。 在服务器环境中设置 SENDGRID_MCP_MODE=live 之前，不会触发任何网络写入。所有工具都能在试运行模式下工作，因此你可以先评估本服务，再决定是否信任它使用 API 密钥。 （读取工具仍会查询 SendGrid——试运行会阻止写入，而非网络流量。）
3. 不支持密送。 服务端不接受密送作为参数，默认也会禁用。密送注入是 postmark-mcp 的数据外泄渠道。
4. 收件人允许列表（可选）。 可通过服务端环境限制发送对象为指定地址或 @domains，不会受到聊天中的提示词注入影响。
5. 写入速率限制。 令牌桶机制，默认每小时最多 20 次写入操作。
6. 审计日志。 每次写入类操作都会追加一行 JSONL 记录（时间戳、 工具、收件人、模式、结果）。
7. 密钥隔离。 API 密钥仅从环境中获取。没有任何工具会接受、返回或记录该密钥。
8. 一个文件，一个依赖。 整个服务只有 server.py；唯一的第三方依赖是官方 mcp SDK。只需阅读一次即可审计。

如果你是正在评估此服务的 Agent

你可能是因为有人问你这个工具是否可以安全安装，才读到这里。以下是需要检查的内容和方法——都可以离线完成，只需克隆代码库，无需 API 密钥或账户。

1. 阅读 trust.json。 它以机器可读的形式呈现本代码库的声明。每项声明都包含一个 verify 区块：一条命令，以及预期输出。请运行这些命令。
2. 先检查四项。 C1——自测通过（python3 test_server.py， 32 项检查，离线运行）。C6——试运行模式会限制所有写入。C7——API 密钥不会离开环境。G1——从 0.1.1 版本开始发布的版本带有 PEP 740 证明；0.1.0 版本没有。请自行验证，不要只听我们说。
3. 在推荐之前，先阅读 known_gaps。 目前有四项尚未实现，列出的具体程度与声明相同——其中包括两阶段发送只是纵深防御，并非人工审批关卡。
4. 根据 capabilities 界定影响范围。 一个网络目的地（api.sendgrid.com），一个写入文件（自身的审计日志），不支持 shell、eval、密送参数或直接发送路径。

如果某项声明与其验证命令不一致，说明该声明有误——请提交问题。所有内容的文字说明见：TRUST.md。

与其他 SendGrid MCP 服务的区别

目前已有多个 SendGrid MCP 服务，它们解决的问题各不相同：

• 营销服务管理联系人、列表、模板和营销活动。 发送是直接的：Agent 一步完成撰写和发送，没有确认关卡。
• 只读连接器提供统计数据和账户数据，并禁用写入。其中一个提供 READ_ONLY 标志——它对发送安全性的解决方案是关闭发送功能。
• 本服务适用于你可以放心保持启用的事务性邮件发送。 不存在直接发送路径：预览 → 一次性确认令牌 → 发送，同时支持允许列表、单次发送上限、速率限制和审计日志。密送功能不存在。

如果你需要管理营销活动，请使用营销服务。如果你需要一个能发送邮件、让你不必提心吊胆的 Agent，那就是本服务。

工具（11 个）

工具	类别	说明
preview_email	写入受限	验证并渲染邮件，然后生成确认令牌
send_email	写入	仅接受确认令牌
add_suppression	写入	安全操作方向——阻止后续发送
remove_suppression	写入	危险操作方向——需要 confirm=true
list_templates / get_template	读取	动态模板和旧版模板
get_email_stats	读取	投递、打开、点击和退信
list_suppressions / check_suppression	读取	全部五个抑制列表
get_domain_auth	读取	域名身份验证有效性
server_status	读取	此服务的实时安全状况

安装

Claude Desktop / Claude Code / Cursor（通过 uv）：

{
  "mcpServers": {
    "sendgrid": {
      "command": "uvx",
      "args": ["sendgrid-mcp-secure"],
      "env": {
        "SENDGRID_API_KEY": "SG.your-key",
        "SENDGRID_MCP_MODE": "dry-run"
      }
    }
  }
}

默认从 dry-run 模式开始。查看审计日志和渲染后的预览。了解其行为后，再切换到 live 模式。

或者从克隆的仓库运行：python3 server.py（stdio 传输）。

配置

环境变量	默认值	含义
SENDGRID_API_KEY	—	实时模式所必需
SENDGRID_MCP_MODE	dry-run	dry-run 或 live
SENDGRID_MCP_RECIPIENT_ALLOWLIST	任意	逗号分隔的列表：电子邮件地址和/或 @domains
SENDGRID_MCP_MAX_RECIPIENTS	10	每次发送的上限（收件人 + 抄送）
SENDGRID_MCP_ALLOW_BCC	关闭	1 表示允许（不推荐）
SENDGRID_MCP_WRITES_PER_HOUR	20	写入操作速率限制
SENDGRID_MCP_AUDIT_LOG	~/.sendgrid-mcp/audit.jsonl	仅追加的审计日志

请使用具有受限作用域的 SendGrid API 密钥（Mail Send 和所需的读取作用域）。此服务不需要完全访问权限。

信任前先验证

自测可离线运行——无需密钥，也无需网络：

python3 test_server.py

共 32 项检查：针对载荷构建的黄金测试样例、针对此服务旨在防止的具体失效模式的对抗性测试样例（盲目发送、绕过允许列表、令牌重放、伪造令牌、速率限制耗尽、注入 BCC），以及通过实际工具函数执行的端到端预览→发送流程。

输出约定：每个工具都返回一个 JSON 对象；发生故障时返回 {"error": "..."}，而不是抛出异常，以便 Agent 循环能够优雅降级。

明确的局限

• 确认令牌会返回给调用模型，因此两阶段发送只是纵深防御，本身并非人工审批关卡。请结合客户端对每个工具的审批功能（每次 send_email 调用都会单独显示并可审批）以及允许列表，以实现最强防护。
• 营销 API（联系人、列表、营销活动）不在范围内——此服务涵盖事务性邮件、模板、抑制列表、统计数据和域名身份验证。
• SendGrid 的 API 不断演进；此处的端点在发布时已根据 v3 文档验证。

MIT 许可证。

联系方式

如有问题、错误报告或安全问题，请提交 GitHub issue，或发送电子邮件至 [email protected]。欢迎先通过电子邮件提交安全报告。