SendGrid Transactional

SendGrid MCP 服务

此服务用于事务性邮件发送与投递，而非覆盖整个 SendGrid API 的地图。

精简的 SendGrid MCP 服务会将 POST /v3/mail/send 作为一个调用，并把其余工具用于联系人、列表和营销活动。这里不涉及这些营销 API。工具遵循 SendGrid 自身投递故障排查所需的检查：

1. 发送前。 sendgrid_validate_send_request 会检查 /v3/mail/send 负载、动态模板版本是否处于启用状态、发件人身份（域名验证或已验证的发件人）、链接品牌设置、收件人抑制项（包括本次发送所用的 ASM 组）、DMARC 警告列表（GET /v3/verified_senders/domains），以及 send_at 是否为未来时间且在 72 小时以内。只有当报告中没有阻止项时，sendgrid_send_with_preflight 才会发起请求。沙盒模式会接受负载，但不会投递邮件。
2. 接受后。 响应头 x-message-id 并不是 msg_id。将其作为 xMessageId 传入；搜索会编译为 msg_id LIKE '<id>%'，然后 sendgrid_get_message_activity 会读取事件链（reason、bounce_type、asm_group_id、outbound_ip）。Email Activity 没有真正的 offset。如果 Activity 返回 403/404，或者区域为 eu 且 Activity 为空，请使用 Email Logs（POST /v3/logs），并通过 to_email 等值筛选。Logs 不接受 msg_id、from_email 和 LIKE。
3. 邮件未送达时。 sendgrid_check_suppression 和 sendgrid_triage_delivery_issue 涵盖退信、拦截、垃圾邮件、无效地址、全局退订和 ASM 组。sendgrid_delete_suppression 可移除一条记录。sendgrid_classify_sendgrid_error 和 sendgrid_get_scopes 可解释 403。已暂停或已取消的定时批次会列出；仅设置了 send_at 的批次，在暂停或取消之前不会出现在该列表中。
4. 发送周边流程。 动态模板（包括批量重命名和清理未启用版本）、Event Webhook 的创建/更新/测试（以及可选的本地接收器），还有会影响投递的控制台设置：域名、链接品牌设置、强制 TLS、邮件和跟踪设置、警报、入站解析。

安装：bunx --no-env-file x @neschadin/sendgrid-mcp。

完整目录和操作手册：MCP_TOOLS.md。

本项目由社区维护，与 Twilio SendGrid 无关联，也未获其认可或赞助。

要求

• Bun ≥ 1.4.3
• 具有所调用工具所需权限范围的 SendGrid API 密钥。密钥通常以 SG. 开头；其他前缀只会记录警告
• SENDGRID_FROM_EMAIL 中的已验证发件人地址
• MCP 客户端（Cursor、Claude Desktop、VS Code 等）

一个进程使用一个 API 密钥。请勿让多个租户共用一个托管实例。

配置

必填

变量	说明
SENDGRID_API_KEY	SendGrid API 密钥
SENDGRID_FROM_EMAIL	默认发件人地址（已验证的发件人）

SendGrid

变量	默认值	说明
SENDGRID_FROM_NAME	SendGrid MCP	默认发件人显示名称
SENDGRID_REGION	global	global 或 eu（不区分大小写）。eu 使用 https://api.eu.sendgrid.com/v3，并在 Activity 为空时回退到 Email Logs
SENDGRID_API_BASE_URL	根据区域设置	覆盖 API 主机。https:// 或 http://
SENDGRID_ON_BEHALF_OF	—	默认的 on-behalf-of 标头：子用户用户名，或 account-id <id>
READ_ONLY	false	true 会在发送请求前阻止发送和修改数据的工具
SENDGRID_MCP_LOG_LEVEL	info	debug、info、warn 或 error

每个工具也接受 onBehalfOf。值 "parent" 会在该次调用中跳过 SENDGRID_ON_BEHALF_OF。使用 sendgrid_list_subusers 列出子用户（父级密钥需要具备相应权限；此密钥可能返回 403）。

握手 instructions 会重复说明区域、API 基础 URL、发件人地址和上述工作流。数组元素与对象成员总数超过 10000 的工具调用会被拒绝。结果会将 oauth_client_secret 和 api_key 的值替换为长度标记。

远程 HTTP

对于 stdio，请将 MCP_TRANSPORT 留空。设置 MCP_TRANSPORT=http，即可在 /mcp 上提供 Streamable HTTP 服务（/health 无需身份验证）。

变量	默认值	说明
MCP_HTTP_HOST	127.0.0.1	绑定地址
MCP_HTTP_PORT	3000	端口
MCP_AUTH_MODE	token	token 或 none。绑定地址不是回环地址时，none 会被拒绝
MCP_AUTH_TOKEN	—	Bearer 令牌。token 模式必填
MCP_ALLOWED_HOSTS	回环地址名称	以逗号分隔的 Host 允许列表。非回环地址时必填
MCP_ALLOWED_ORIGINS	回环地址名称	以逗号分隔的 Origin 允许列表。允许缺少 Origin
MCP_TLS_KEY_FILE	—	TLS 密钥。与 MCP_TLS_CERT_FILE 一起设置
MCP_TLS_CERT_FILE	—	TLS 证书
MCP_TRUST_PROXY	false	仅在自有 TLS 代理之后，允许非回环地址使用明文 HTTP

本地事件 Webhook 接收器

默认关闭；设置 SENDGRID_EVENT_WEBHOOK_PORT 后启用。缓冲区存储在内存中（默认 5000 个事件），进程退出时会丢弃。

变量	默认值
SENDGRID_EVENT_WEBHOOK_HOST	0.0.0.0
SENDGRID_EVENT_WEBHOOK_PATH	/sendgrid/events
SENDGRID_EVENT_WEBHOOK_HEALTH_PATH	/sendgrid/events/health
SENDGRID_EVENT_WEBHOOK_MAX_EVENTS	5000
SENDGRID_EVENT_WEBHOOK_VERBOSE	false
SENDGRID_EVENT_WEBHOOK_REQUIRE_SIGNATURE	false
SENDGRID_EVENT_WEBHOOK_PUBLIC_KEY	签名为必需项时必须设置

将 SendGrid Event Webhook URL 指向隧道，例如 https://<ngrok-host>/sendgrid/events。使用 sendgrid_get_received_webhook_events 和 sendgrid_get_webhook_receiver_status 查看收到的内容。使用 sendgrid_manage_event_webhook 创建或测试 SendGrid 端的 Webhook。

MCP 客户端配置

Cursor

mcp.json.example。--no-env-file 可阻止 Bun 同时读取客户端当前工作目录中的 .env。在 ~/.cursor/mcp.json 中，envFile 必须是绝对路径。

{
  "mcpServers": {
    "sendgrid": {
      "command": "bunx",
      "args": ["--no-env-file", "x", "@neschadin/sendgrid-mcp"],
      "envFile": "${workspaceFolder}/.env"
    }
  }
}

启动服务进程并设置 MCP_TRANSPORT=http 后，可使用远程 HTTP：

{
  "mcpServers": {
    "sendgrid": {
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer <MCP_AUTH_TOKEN>"
      }
    }
  }
}

Claude Desktop

不使用 envFile。桌面应用的当前工作目录不是你的代码仓库，因此请传入绝对路径的 --env-file：

{
  "mcpServers": {
    "sendgrid": {
      "command": "bunx",
      "args": [
        "--no-env-file",
        "--env-file=/absolute/path/.env",
        "x",
        "@neschadin/sendgrid-mcp"
      ]
    }
  }
}

更改 MCP 配置后，请重启客户端。

安全

• 发送工具可能会将真实邮件加入队列。它们不会要求提供 confirmToken。请使用 sendgrid_send_with_preflight，或设置 READ_ONLY=true。
• 会更改 SendGrid 的工具（模板、抑制列表、Webhook、域名、设置、计划发送的暂停/取消）需要 confirmToken "CONFIRM"。
• READ_ONLY=true 会在发出 HTTP 请求前阻止发送和上述变更操作。
• Email Activity（/v3/messages）可能需要 Email Activity 附加组件。

开发

Git 标签 vX.Y.Z 必须与 package.json 中的 version 以及 server.json 中的两个版本字段一致。该标签会运行测试、创建 GitHub Release、将 @neschadin/sendgrid-mcp 发布到 npm，然后将 io.github.Neschadin/sendgrid-mcp 发布到 MCP 注册表。该版本不包含二进制资源。预发布标签（vX.Y.Z-...）会使用 next dist-tag 发布到 npm，跳过 MCP 注册表，并在 GitHub 上标记为预发布版本。

git clone https://github.com/Neschadin/sendgrid-mcp.git
cd sendgrid-mcp
bun install
bun run dev          # stdio MCP; loads .env
bun run lint
bun run typecheck
bun run smoke
bun test

bun run inspect

文档

• MCP_TOOLS.md — 工具、操作手册、风险矩阵
• SendGrid API 参考
• 面向开发者的 SendGrid

许可证

MIT — 详见 LICENSE。