Novu MCP

Novu MCP 服务

访问我们的 GitHub 主仓库 »

✨ 功能

一个 MCP 服务即可为 AI Agent 解锁整个 Novu 工作区：

• Agent — 创建、列出、检查和更新 Novu Agent，并将渠道连接交由 Novu CLI 操作手册处理
• 对话 — 列出 Agent 会话线程，并检查活动时间线（消息、审批、MCP 连接）
• 通知 — 获取和筛选事件，并查看完整的执行日志和投递状态
• 订阅者 — 按电子邮件、电话、姓名或 ID 搜索和管理接收者
• 工作流 — 列出、检查、创建、更新和触发通知工作流
• 偏好设置 — 读取和更新订阅者的渠道偏好设置（电子邮件、SMS、应用内通知、推送、聊天）
• 环境 — 查看环境及其配置
• 集成 — 管理各渠道的服务提供商集成
• 身份验证与身份信息 — whoami 验证你的凭据（OAuth 或 API 密钥）并报告当前区域

🚀 快速开始

你无需自行托管任何内容——该服务完全托管。选择对应 Novu Cloud 区域的端点，并将 MCP 客户端指向该端点：

区域	端点	Novu API
美国	https://mcp.novu.co/	api.novu.co
欧盟	https://eu.mcp.novu.co/	eu.api.novu.co

每个主机都是固定部署在其所在区域的专用实例——不再使用 ?region= 查询参数。（为保证向后兼容，如果 ?region= 与主机所在区域不匹配，服务会返回 400，并告知正确的端点。）

身份验证

此服务支持两种身份验证方式，且在两个区域端点上的工作方式完全相同：

1. OAuth（推荐） — 无需复制粘贴 API 密钥。MCP 客户端首次连接时，服务会返回 401 和 OAuth 发现文档（/.well-known/oauth-protected-resource），该文档会将客户端指向 Novu 的授权服务器（Clerk）。客户端会打开 Novu 登录和授权页面，你选择一个组织，客户端便会自动收到访问令牌。

任何支持远程 OAuth 的 MCP 客户端（Cursor、Claude、ChatGPT、Windsurf，……）都会为你处理此流程——只需添加服务 URL，无需添加标头。

注意：客户端必须请求 user:org:read 范围（发现文档中会公布该范围），以便 Novu API 解析你的组织。如果你的 Novu 账户属于多个组织，授权时系统会要求你选择一个。

2. API 密钥 — 将你从 Novu Dashboard 获取的密钥作为 bearer 令牌提供：

Authorization: Bearer <your-novu-api-key>

提供 API 密钥后，服务会将会话视为 API 密钥模式，并且不会触发 OAuth 登录流程，即使是在托管端点上也是如此。密钥绑定到单个环境（因此也绑定到对应区域），无需额外配置；只需连接到你的账户所在区域对应的端点。

自托管 Novu？ OAuth 仅适用于 Novu Cloud（US/EU）——此流程通过 Novu Cloud 的授权服务器运行，自托管部署无法访问该服务器。自托管部署始终使用 API 密钥进行身份验证。请参阅部署自己的实例和本地开发。

🎯 环境

请求如何映射到 Novu 环境取决于你的身份验证方式：

• API 密钥 — 密钥本身绑定到单个环境；请求始终针对该环境执行。
• OAuth — 令牌绑定到你的组织，Novu API 默认使用开发环境。

对于 OAuth 会话，每个工具都接受可选的 environmentId 参数，用于指定特定环境（该参数会作为 Novu-Environment-Id 标头转发给 Novu API）。先调用 get_environments 列出你的环境，然后传入所需环境的 _id——例如，查看生产环境的通知。Novu API 会验证该环境是否属于你的组织。使用 API 密钥时，此参数会被忽略——密钥已固定到对应环境。

本地／自托管 API — 若要将此 MCP 服务指向其他位置运行的 Novu API（例如，在 http://localhost:3000 上运行的自托管实例），请在 .dev.vars 中设置 NOVU_API_URL，然后在本地运行服务（请参阅本地开发）。这取代了旧的 ?region=local 查询参数。自托管部署始终使用 API 密钥——OAuth 仅适用于 Novu Cloud。

🛠️ 用法

此服务通过 https://mcp.novu.co/（US）和 https://eu.mcp.novu.co/（EU）使用 Streamable HTTP MCP 传输协议。

Cursor、Windsurf、Claude 和其他支持 OAuth 的客户端

任何支持通过 OAuth 连接远程 MCP 服务的客户端，都可以在不添加标头的情况下连接——客户端会为你运行登录流程：

• URL（US）： https://mcp.novu.co/
• URL（EU）： https://eu.mcp.novu.co/

首次连接时，客户端会打开 Novu 登录和授权页面。批准授权并选择组织后，工具便会自动显示。

API 密钥（mcp-remote／stdio 客户端、自托管 Novu）

对于仅支持 stdio 传输的客户端、偏好使用静态 API 密钥的情况，或运行自托管 Novu实例的情况（此类实例不支持 OAuth），请使用 mcp-remote 代理并设置 Authorization 标头。提供 API 密钥可避免客户端启动 OAuth 流程：

{
  "mcpServers": {
    "novu": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.novu.co/",
        "--header",
        "Authorization:Bearer your-novu-api-key"
      ]
    }
  }
}

对于 EU 区域，请将 URL 替换为 https://eu.mcp.novu.co/。

📦 可用工具

工具	描述
whoami	显示已通过身份验证的用户（通过 Novu API 验证凭据）和当前区域
create_agent	创建 Agent（默认为托管演示版 Claude；无需 API 密钥）
connect_agent	返回命令行操作指南，用于将渠道连接到现有 Agent
get_agents	使用游标分页列出 Agent
get_agent	按标识符获取单个 Agent
update_agent	更新 Agent 的名称、状态、桥接 URL 或行为
get_conversations	列出 Agent 对话，可按 Agent、订阅者、状态和提供方筛选
get_conversation_activities	查看对话时间线（精简的调试摘要；使用 verbose 查看原始 JSON）
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 20+ 和 pnpm。

# Clone and install
git clone https://github.com/novuhq/novu-mcp-server.git
cd novu-mcp-server
pnpm install

# Start the local worker
pnpm dev

服务运行在 http://localhost:8787。将 MCP 客户端指向该地址，方法与连接托管版本相同：

{
  "mcpServers": {
    "novu": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8787/",
        "--header",
        "Authorization:Bearer your-novu-api-key"
      ]
    }
  }
}

配置从 .dev.vars（已加入 gitignore）读取——复制 .dev.vars.example 即可开始。主要变量如下：

• NOVU_API_URL — 此服务代理到的 Novu API（例如，自托管 API 使用 http://localhost:3000 ，云端则使用 https://api.novu.co / https://eu.api.novu.co）。
• NOVU_REGION — whoami 显示的区域标签。
• CLERK_OAUTH_ISSUER — 用于 OAuth 的 Clerk 授权服务器。留空可完全禁用 OAuth， 并仅使用 API 密钥运行（自托管模式）。

如需在本地开发时连接运行于 http://localhost:3000 的自托管 Novu API， 请在 .dev.vars 中设置 NOVU_API_URL="http://localhost:3000"，并使用实例的 API 密钥（OAuth 仅适用于 Novu Cloud）：

{
  "mcpServers": {
    "novu-local": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8787/",
        "--header",
        "Authorization:Bearer your-local-novu-api-key"
      ]
    }
  }
}

本地开发中的 OAuth

如需在本地测试 OAuth，请在 .dev.vars 中将 CLERK_OAUTH_ISSUER 设置为 Novu API 信任的 Clerk 授权服务器（例如，美国区域使用 https://clerk.dashboard.novu.co）。MCP 端点源自请求 URL，因此请运行开发服务 并将 MCP 客户端指向相同的 URL（例如 http://localhost:8787/）。 RFC 9728 要求 PRM 的 resource 字段必须与 MCP 端点 URL 完全一致； 如果连接时使用的主机或端口与服务绑定的地址不同，Cursor 等客户端会丢弃元数据，并在注册时不包含 user:org:read 范围。

当 CLERK_OAUTH_ISSUER 为空时，OAuth 发现端点会返回 404，而 401 响应中不会包含 OAuth 元数据，因此客户端会回退到 API 密钥身份验证。

部署你自己的实例

该服务是一个标准的 Cloudflare Worker。wrangler.jsonc 的组织方式如下：顶层配置仅用于本地开发（没有 routes，因此 wrangler dev 会在 localhost 上提供服务，OAuth 发现也会公布 localhost 源站），而实际部署则位于具名环境下：

• pnpm deploy → --env us（绑定 mcp.novu.co，NOVU_API_URL=https://api.novu.co）
• pnpm deploy:eu → --env eu（绑定 eu.mcp.novu.co，NOVU_API_URL=https://eu.api.novu.co）

要部署你自己的实例，请 fork 此仓库，并在 env 下添加一个环境（或编辑现有环境），配置你自己的 routes、NOVU_API_URL 和 NOVU_REGION，然后使用 wrangler deploy --env <name> 部署。自托管实例开箱即用，可通过 API 密钥对 NOVU_API_URL 指向的任何地址进行身份验证，包括自托管的 Novu API。要在自己的部署中使用 OAuth，必须将 CLERK_OAUTH_ISSUER 密钥设置为 Novu API 所信任的授权服务器（wrangler secret put CLERK_OAUTH_ISSUER --env <name>）；仅使用 API 密钥时请将其留空。

脚本

• pnpm dev — 通过 Wrangler 在本地运行 Worker（顶层、无路由配置）
• pnpm deploy — 部署美国 Worker（mcp.novu.co，--env us）
• pnpm deploy:eu — 部署欧盟 Worker（eu.mcp.novu.co，--env eu）
• pnpm type-check — 运行 TypeScript 类型检查
• pnpm lint:fix — 使用 Biome 修复代码检查问题
• pnpm format — 使用 Biome 格式化代码库

项目结构

src/
├── index.ts            # Worker entry — auth extraction and routing
├── oauth.ts            # OAuth discovery, 401 bootstrap, initialize-time probe
├── server/NovuMCP.ts   # Durable Object hosting the MCP agent
├── tools/              # One file per tool group (workflows, subscribers, …)
├── utils/              # API client, validation, tool factory
└── types/              # Shared TypeScript types

要添加新工具，请在 src/tools/ 下创建一个 register*Tools 函数，并在 src/server/NovuMCP.ts 中接入。

🔒 安全

• 此服务是纯 OAuth 透传：不会签发、交换或重新签名令牌。它自身从不验证令牌，而是公布 Novu 的 Clerk 授权服务器，并将调用方的 Authorization 标头原样转发给 Novu API，由后者验证令牌并解析组织和权限。
• OAuth 访问令牌（Clerk 不透明的 oat_… 令牌）有效期较短，并且可以从 Novu 端撤销，因此比长期有效的 API 密钥安全得多。
• 无论是 OAuth 令牌还是旧版 API 密钥，凭证都限定于你的 MCP 会话：它通过运行时的 props 通道交给会话的 Durable Object，绝不会放在 URL 中（否则会泄露到请求日志里），并会在会话结束时丢弃。服务本身不持有任何环境凭证。
• 切勿提交 API 密钥或签发方配置。本地值请使用 .dev.vars（该文件已加入 gitignore）。
• 请像保护密码一样保护 Novu API 密钥；如果怀疑密钥已泄露，请从控制面板轮换。

🤝 贡献

1. 进行更改

   git checkout -b feat/your-change
   pnpm dev           # Test locally
   pnpm type-check    # Verify types
   git commit -m "feat: your change"
   git push origin feat/your-change
   

2. 发起 Pull Request

   • 使用描述性标题，并添加 feat:、fix:、docs: 或 chore: 前缀
   • 简要说明更改内容，并在适用时附上工具调用示例

指南：

• 工具描述应简洁，因为它们会原样提供给大模型
• 使用 src/utils/ 中的 Zod 架构验证输入
• 对于标准 CRUD 端点，优先使用 ToolFactory 辅助函数
• 缺少什么内容？请提交 GitHub issue

需要帮助？ 请发送邮件至 [email protected]，或加入 Discord。

---

感谢你的贡献！🙏