内容
<div align="center">
<a href="https://novu.co?utm_source=github" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/2233092/213641039-220ac15f-f367-4d13-9eaf-56e79433b8c1.png">
<img alt="Novu Logo" src="https://user-images.githubusercontent.com/2233092/213641043-3bbb3f21-3c53-4e67-afe5-755aeb222159.png" width="280"/>
</picture>
</a>
</div>
<br/>
<p align="center">
<a href="https://www.producthunt.com/products/novu">
<img src="https://img.shields.io/badge/Product%20Hunt-Golden%20Kitty%20Award%202023-yellow" alt="Product Hunt">
</a>
<a href="https://news.ycombinator.com/item?id=38419513"><img src="https://img.shields.io/badge/Hacker%20News-%231-%23FF6600" alt="Hacker News"></a>
<a href="https://www.npmjs.com/package/@novu/js">
<img src="https://img.shields.io/npm/dm/@novu/js" alt="npm downloads">
</a>
</p>
<h1 align="center">Novu MCP 服务器</h1>
<div align="center">
Novu 的模型上下文协议（MCP）服务器 - 将 AI 助手直接集成到您的通知工作流中。管理订阅者、触发工作流、检查事件和调整偏好设置，适用于任何与 MCP 兼容的客户端。
</div>
<p align="center">
<br />
<a href="https://github.novu.co?utm_campaign=gh_org_profile&utm_source=github" rel="dofollow"><strong>访问我们的主 GitHub 仓库 »</strong></a>
<br />
</p>
# Novu MCP 服务器
## ✨ 功能
一个 MCP 服务器，解锁您的整个 Novu 工作空间，适用于 AI 代理：
- **通知** — 获取和过滤事件，附带完整的执行日志和投递状态
- **订阅者** — 按电子邮件、电话、姓名或 ID 搜索和管理接收者
- **工作流** — 列出、检查、创建、更新和触发通知工作流
- **偏好设置** — 读取和更新订阅者的频道偏好设置（电子邮件、短信、应用内、推送、聊天）
- **环境** — 查看环境及其配置
- **集成** — 管理跨频道的提供商集成
- **API 密钥管理** — 验证 API 密钥状态和活动区域
## 🚀 快速开始
您不需要托管任何内容 - 服务器完全托管在 `mcp.novu.co`。
**前提条件：** Novu 账户和来自 [Novu 仪表盘](https://web.novu.co/settings) 的 API 密钥。
```bash
# 直接开始 - 只需将您的 MCP 客户端指向：
https://mcp.novu.co/
```
使用标准 bearer token 进行身份验证：
服务器支持美国、欧盟和本地区域，以指向自托管的 Novu API。使用 `region` 参数指定您首选的区域：
**美国区域** （如果未指定参数，则默认为）：
```
Authorization: Bearer <您的 Novu API 密钥>
```
## 🌍 区域
服务器支持两个 Novu 云区域。在查询参数中传递区域：
| 区域 | 端点 |
| ------ | ------------------------------- |
| 美国（默认） | `https://mcp.novu.co/?region=us` |
| 欧盟 | `https://mcp.novu.co/?region=eu` |
**本地区域** （指向运行在 `http://localhost:3000` 上的本地 Novu API）：
```
# 可流式 HTTPS/MCP
http://localhost:8787/?region=local
# SSE（已弃用）
http://localhost:8787/sse?region=local
```
**注意：** 如果未提供区域参数，服务器默认使用美国区域（`api.novu.co`）。对于欧盟区域，它连接到 `eu.api.novu.co`。`local` 区域针对 `http://localhost:3000`，旨在针对自托管的 Novu API 进行开发 - 仅当此 MCP 服务器通过 `pnpm start` 在本地运行时（Wrangler 的默认本地模式），因为 Cloudflare 的边缘运行时无法访问您的机器的 localhost。
如果未提供 `region`，服务器默认使用美国区域（`api.novu.co`）。欧盟区域代理到 `eu.api.novu.co`。
## 🛠️ 用法
服务器在 `https://mcp.novu.co/` 处使用可流式 HTTP MCP 传输协议。
### Claude 桌面版
安装 [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) 代理，并将以下内容添加到您的 Claude 桌面版配置中：
```json
{
"mcpServers": {
"novu": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.novu.co/",
"--header",
"Authorization:Bearer 您的 Novu API 密钥"
]
}
}
}
```
对于欧盟区域，请将 URL 替换为 `https://mcp.novu.co/?region=eu`。
重启 Claude 桌面版 - Novu 工具将自动出现。
### Cursor、Windsurf 及其他 MCP 客户端
任何支持远程 MCP 服务器的客户端都可以直接连接：
- **URL:** `https://mcp.novu.co/` （添加 `?region=eu` 表示欧盟）
- **头部：** `Authorization: Bearer 您的 Novu API 密钥`
对于仅支持 stdio 传输的客户端，请像上面的 Claude 桌面版示例一样使用 `mcp-remote`。
## 📦 可用工具
| 工具 | 描述 |
| ---- | ----------- |
| `get_api_key_status` | 检查当前 API 密钥状态和活动区域 |
| `get_environments` | 列出所有环境及其详细信息和 API 密钥 |
| `get_notifications` | 获取事件，并按频道、模板、订阅者、日期等进行筛选 |
| `get_notification` | 获取具有详细执行日志的特定通知 |
| `find_subscribers` | 按电子邮件、姓名、电话或 ID 搜索订阅者 |
| `get_subscriber_preferences` | 获取订阅者跨所有频道和工作流的偏好设置 |
| `update_subscriber_preferences` | 更新订阅者的频道偏好设置（全局或按工作流） |
| `get_workflows` | 列出所有工作流及其基本信息 |
| `get_workflow` | 获取工作流的完整定义、步骤和有效载荷模式 |
| `trigger_workflow` | 为订阅者触发具有自定义有效载荷的工作流 |
| `get_integrations` | 列出已配置的跨频道提供商集成 |
## 💻 本地开发
**前提条件：** [Node.js](https://nodejs.org/) 20+ 和 [pnpm](https://pnpm.io/installation)。
```bash
# 克隆并安装
git clone https://github.com/novuhq/novu-mcp-server.git
cd novu-mcp-server
pnpm install
# 启动本地工作进程
pnpm dev
```
服务器运行在 [http://localhost:8787](http://localhost:8787)。像使用托管版本一样，将您的 MCP 客户端指向它：
```json
{
"mcpServers": {
"novu": {
"command": "npx",
"args": [
"mcp-remote",
"http://localhost:8787/",
"--header",
"Authorization:Bearer 您的 Novu API 密钥"
]
}
}
}
```
对于针对 **自托管 Novu API** 的本地开发，在 `http://localhost:3000` 上添加 `?region=local`：
```json
{
"mcpServers": {
"novu-local": {
"command": "npx",
"args": [
"mcp-remote",
"http://localhost:8787/?region=local",
"--header",
"Authorization:Bearer 您的本地 Novu API 密钥"
]
}
}
}
```
#### 方法 2：SSE（已弃用）
- `pnpm dev` — 通过 Wrangler 在本地运行工作进程
- `pnpm deploy` — 部署到 Cloudflare Workers
- `pnpm type-check` — 运行 TypeScript 类型检查
- `pnpm lint:fix` — 使用 Biome 修复 linter 问题
- `pnpm format` — 使用 Biome 格式化代码库
### 项目结构
```
src/
├── index.ts # 工作进程入口 - 身份验证提取和路由
├── server/NovuMCP.ts # 托管 MCP 代理的 Durable 对象
├── tools/ # 每个工具组一个文件（工作流、订阅者、...）
├── utils/ # API 客户端、验证、工具工厂
└── types/ # 共享 TypeScript 类型
```
通过在 `src/tools/` 下创建 `register*Tools` 函数并在 `src/server/NovuMCP.ts` 中连接它来添加新工具。
## 🔒 安全
- 您的 API 密钥通过每个请求的 `Authorization` 头部传递 - 它永远不会在服务器端存储。
- 所有发往 Novu API 的出站请求都使用调用者的密钥进行身份验证；服务器不持有任何环境凭证。
- 永远不要提交 API 密钥。对于本地机密，请使用 `.dev.vars` （已经 gitignored）。
- 将您的 Novu API 密钥像密码一样对待 - 如果您怀疑它已被泄露，请从仪表盘中轮换它。
## 🤝 贡献
1. **进行更改**
```bash
git checkout -b feat/您的更改
pnpm dev # 在本地测试
pnpm type-check # 验证类型
git commit -m "feat: 您的更改"
git push origin feat/您的更改
```
2. **打开拉取请求**
- 使用描述性标题，带有 `feat:`、`fix:`、`docs:` 或 `chore:` 前缀
- 包括更改的简要描述，以及相关时提供示例工具调用
**指南：
- 保持工具描述简洁 - 它们直接显示给 LLM
- 在 `src/utils/` 中使用 Zod 模式验证输入
- 优先使用 `ToolFactory` 助手进行标准 CRUD 端点
- 缺少某些内容？打开 [GitHub 问题](https://github.com/novuhq/novu-mcp-server/issues)
**需要帮助？** 请发送电子邮件至 support@novu.co 或加入 [Discord](https://discord.novu.co)。
---
感谢您的贡献！ 🙏
