内容
<p align="center">
<img src="assets/sendgrid-logo.png" alt="SendGrid" width="320" />
</p>
# SendGrid MCP 服务器
SendGrid 的 MCP 服务器：具有预检检查、模板管理、投递诊断、帐户/控制台设置和可选的本地事件 Webhook 捕获的事务性电子邮件。
**最终用户运行单个编译后的二进制文件 — 不需要 Bun。**
联系人/列表营销 CRUD 功能故意不在此范围内。
本项目由社区维护，不隶属于、也不被 Twilio SendGrid 认可或赞助。
## 功能
- **安全发送** — `validate_send_request`、`send_with_preflight`、沙盒模式
- **模板** — 列表/创建/更新/激活动态模板
- **诊断** — 电子邮件活动、抑制、统计、错误分类、投递分类
- **Webhook** — SendGrid 中的事件 Webhook 配置 + 可选的本地接收器（支持 ngrok）
- **帐户和控制台** — 验证的发件人、域名身份验证、邮件/跟踪设置、警报、入站解析
完整工具目录：[`MCP_TOOLS.md`](./MCP_TOOLS.md)
## 安装（二进制文件）
从 [GitHub Releases](https://github.com/Neschadin/sendgrid-mcp/releases) 下载适用于您操作系统的二进制文件。
| 平台 | 资产 |
|----------|--------|
| Linux x64 | `sendgrid-linux-x64` |
| Linux arm64 | `sendgrid-linux-arm64` |
| macOS Intel | `sendgrid-darwin-x64` |
| macOS Apple Silicon | `sendgrid-darwin-arm64` |
| Windows x64 | `sendgrid-windows-x64.exe` |
```bash
chmod +x sendgrid-linux-x64
mv sendgrid-linux-x64 ~/.local/bin/sendgrid
```
二进制文件使用 `bun build --compile` 构建，**嵌入 Bun 运行时**。用户无需安装 Bun。
## 要求
- 具有您使用的工具作用域的 [SendGrid API 密钥](https://app.sendgrid.com/settings/api_keys)
- 一个与 `SENDGRID_FROM_EMAIL` 匹配的**验证发件人**地址
- 一个 MCP 客户端（Cursor、Claude Desktop、VS Code 等）
每个用户使用**他们自己的** API 密钥（自带密钥）本地运行服务器。不要使用共享凭证共享一个托管实例。
## 配置
### 必需环境变量
| 变量 | 描述 |
|----------|-------------|
| `SENDGRID_API_KEY` | SendGrid API 密钥 (`SG....`) |
| `SENDGRID_FROM_EMAIL` | 默认发件人地址（验证发件人） |
### 可选
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `SENDGRID_FROM_NAME` | `SendGrid MCP` | 默认发件人显示名称 |
| `SENDGRID_REGION` | `global` | 使用 `eu` 表示 `https://api.eu.sendgrid.com/v3` |
| `SENDGRID_API_BASE_URL` | `https://api.sendgrid.com/v3` | 完整的 SendGrid API 基本 URL 重定向 |
| `SENDGRID_MCP_LOG_LEVEL` | `info` | `debug` \| `info` \| `warn` \| `error` |
### 可选：本地事件 Webhook 接收器
仅当设置了 `SENDGRID_EVENT_WEBHOOK_PORT` 时启用。
| 变量 | 默认值 |
|----------|---------|
| `SENDGRID_EVENT_WEBHOOK_PORT` | *(禁用)* |
| `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 事件 Webhook URL 指向您的隧道，例如 `https://<ngrok-host>/sendgrid/events`。通过 MCP 工具 `get_received_webhook_events` / `get_webhook_receiver_status` 检查事件。
对于公共隧道，优先使用签名 Webhook 验证：
`SENDGRID_EVENT_WEBHOOK_REQUIRE_SIGNATURE=true` 和
`SENDGRID_EVENT_WEBHOOK_PUBLIC_KEY=<SendGrid 公共密钥>`。
## MCP 客户端设置
### Cursor
设置 → MCP → 添加服务器（或编辑 `~/.cursor/mcp.json`）：
```json
{
"mcpServers": {
"sendgrid": {
"command": "/absolute/path/to/sendgrid",
"args": [],
"env": {
"SENDGRID_API_KEY": "SG.xxx",
"SENDGRID_FROM_EMAIL": "you@yourdomain.com",
"SENDGRID_FROM_NAME": "Your App"
}
}
}
}
```
### Claude Desktop
```json
{
"mcpServers": {
"sendgrid": {
"command": "/absolute/path/to/sendgrid",
"args": [],
"env": {
"SENDGRID_API_KEY": "SG.xxx",
"SENDGRID_FROM_EMAIL": "you@yourdomain.com"
}
}
}
}
```
更改 MCP 配置后重启客户端。
## 安全
- **发送工具** 可以排队真正的电子邮件。优先在自动化中使用 `send_with_preflight`。
- **变更控制台工具** 需要 `confirmToken: "CONFIRM"` （警报、邮件/跟踪设置、验证发件人、域名、Webhook）。
- **电子邮件活动** （`/v3/messages`）可能需要 [电子邮件活动插件](https://www.twilio.com/docs/sendgrid/api-reference/email-activity/filter-all-messages)。
## 开发（仅限维护者）
Bun 仅在**从源代码构建**时需要，而不需要运行发布二进制文件。
```bash
git clone https://github.com/Neschadin/sendgrid-mcp.git
cd sendgrid-mcp
bun install
bun run dev # 从 TypeScript 运行 stdio MCP
bun run build # 编译 → bin/sendgrid（本地平台）
./scripts/build-release.sh # 所有发布目标 → dist/
bun run lint
bun run typecheck
bun run smoke
```
### MCP 检验
```bash
SENDGRID_API_KEY=SG.xxx SENDGRID_FROM_EMAIL=you@domain.com bun run inspect
```
## 文档
- [MCP_TOOLS.md](./MCP_TOOLS.md) — 工具、运行手册、风险矩阵
- [SendGrid API 参考](https://www.twilio.com/docs/sendgrid/api-reference)
- [SendGrid 开发者](https://www.twilio.com/docs/sendgrid/for-developers)
## 许可证
MIT — 请参阅 [LICENSE](./LICENSE)。
