内容
# NodeRed-MCP
> **⚠️ 重要声明**
>
> 本MCP服务器提供对Node-RED实例管理API的**编程化、无人值守访问**。使用此服务器的AI代理可以创建、修改、删除流程，注入消息，并通过Function节点执行任意代码，包括可能破坏或永久损坏您的Node-RED环境及其连接系统的操作。
>
> **本软件** **不适用于生产环境**。它仅用于开发、实验和学习目的。
>
> 使用本软件，即表示您确认：
> - **自行承担风险**。作者和贡献者不提供任何明示或暗示的保证，不承担因使用本软件而导致的任何直接或间接损害、数据丢失、服务中断或安全事件的责任。
> - 您**完全负责**：
> - 限制对MCP服务器的网络访问
> - 配置身份验证（`MCP_API_KEY` 或 `MCP_OAUTH_ENABLED`）
> - 在部署前验证AI代理的操作是否安全
> - 维护流程备份
> - **在没有反向代理、强认证和TLS的情况下，绝不能将此服务器暴露在公共互联网上**。
> - **绝不能在包含敏感数据、业务关键流程或生产基础设施的Node-RED实例上授予此服务器访问权限**。
>
> 如果您选择运行此服务器，则完全自行承担风险。
用于通过管理API控制Node-RED实例的MCP（模型上下文协议）服务器。连接LLM驱动的工具到Node-RED流程。
## 快速入门
```bash
cp .env.example .env
# 编辑.env文件，填写您的Node-RED URL
npm install
npm run start:http
```
## 身份验证
MCP服务器支持HTTP传输的两种身份验证方法。两种方法都是可选的——如果两种方法都没有配置，服务器将开放运行（向后兼容）。
### API密钥（推荐用于大多数部署）
设置 `MCP_API_KEY` 环境变量：
```bash
# 生成安全密钥
openssl rand -hex 32
# 添加到.env文件
MCP_API_KEY=您的生成的密钥
```
客户端必须包含密钥作为Bearer令牌：
```
Authorization: Bearer 您的生成的密钥
```
### OAuth 2.0（用于多客户端部署）
启用具有动态客户端注册和PKCE的OAuth 2.0：
```bash
MCP_OAUTH_ENABLED=true
MCP_OAUTH_ISSUER_URL=https://您的服务器.example.com
```
服务器暴露标准OAuth端点：
| 端点 | 描述 |
|---|---|
| `POST /register` | 动态客户端注册 |
| `GET /authorize` | 授权码流程（PKCE） |
| `POST /token` |令牌颁发和刷新 |
| `POST /revoke` |令牌吊销 |
| `GET /.well-known/oauth-authorization-server` | RFC 8414 元数据 |
| `GET /.well-known/oauth-protected-resource/mcp` | RFC 9728 元数据 |
MCP客户端通过知名端点自动发现OAuth，无需除了服务器URL之外的手动配置。
### 两种方法
当同时配置了`MCP_API_KEY`和`MCP_OAUTH_ENABLED=true`时，有效的API密钥或有效的OAuth访问令牌都可以授予访问权限。
### 无身份验证
当未配置`MCP_API_KEY`和`MCP_OAUTH_ENABLED`时，服务器在没有身份验证的情况下运行（适用于本地开发）。
## 连接到Node-RED实例
本节介绍MCP服务器如何身份验证到Node-RED管理API——不要与上面的[MCP服务器身份验证](#身份验证)部分混淆，后者保护对MCP服务器本身的访问。
客户端通过在启动时调用`GET /auth/login`来自动检测身份验证模式，除非设置了`NODERED_API_KEY`（跳过检测）。
### 无身份验证
如果您的Node-RED实例未配置`adminAuth`，则不需要额外的变量。
### 标准凭证（`type: "credentials"`）
设置用户名和密码。客户端调用`POST /auth/token`以获取Bearer令牌。
```env
NODERED_USERNAME=admin
NODERED_PASSWORD=您的密码
```
### OIDC / 自定义策略（`type: "oidc"` 或类似）
OIDC使用**带有PKCE的授权码流程**，需要浏览器——MCP服务器是无头的，无法交互完成流程。
支持的方法是在Node-RED的`settings.js`中**添加API密钥和OIDC**，使用`tokens`函数：
```js
adminAuth: {
type: "oidc",
// ... 您的OIDC提供商配置 ...
tokens: async (token) => {
if (token === "mcp-server-secret-key-here") {
return { username: "mcp-server", scope: "*" }
}
return null
}
}
```
然后配置MCP服务器：
```env
NODERED_API_KEY=mcp-server-secret-key-here
```
当设置了`NODERED_API_KEY`时，客户端跳过自动检测调用，并直接使用它作为每个请求的Bearer令牌。
### 原生API密钥（`NODERED_API_KEY`）
如果您的Node-RED实例已经公开了API密钥（例如，通过`tokens`函数或自定义策略），只需设置：
```env
NODERED_API_KEY=您的API密钥
```
> **注意**：`NODERED_API_KEY`优先于`NODERED_USERNAME`/`NODERED_PASSWORD`。如果两者都设置了，则使用API密钥。
## 配置参考
| 变量 | 必需 | 默认值 | 描述 |
|---|---|---|---|
| `NODERED_URL` | **是** | — | Node-RED实例URL |
| `NODERED_USERNAME` | 否 | — | Node-RED凭证身份验证（`type: "credentials"`） |
| `NODERED_PASSWORD` | 否 | — | Node-RED凭证身份验证（`type: "credentials"`） |
| `NODERED_API_KEY` | 否 | — | Node-RED API密钥身份验证（OIDC、自定义策略或原生API密钥） |
| `MCP_HTTP_PORT` | 否 | `3000` | HTTP传输端口 |
| `MCP_API_KEY` | 否 | — | MCP服务器身份验证的API密钥 |
| `MCP_OAUTH_ENABLED` | 否 | `false` | 启用OAuth 2.0服务器 |
| `MCP_OAUTH_ISSUER_URL` | 条件 | — | OAuth颁发者基准URL |
| `MCP_OAUTH_CLIENTS_FILE` | 否 | `./oauth-clients.json` | OAuth客户端注册表 |
| `MCP_OAUTH_TOKENS_FILE` | 否 | `./oauth-tokens.json` | OAuth令牌存储 |
## 传输
- **stdio** （默认）：`npm run start:stdio` — 用于本地MCP客户端集成
- **HTTP**：`npm run start:http` — 可流式传输的HTTP，带有可选身份验证，WebSocket分阶段查看器位于 `/staging-ws`
参见 [docs/deployment-guide.md](docs/deployment-guide.md) 以获取详细的部署指南，涵盖stdio、HTTP和Docker Compose。
## 安装
您可以在`mcp.json`文件中配置MCP，方法是指向npm包`@gmag11/nodered-mcp-server`并传递所需的环境变量。
```json
{
"servers": {
"nodered-mcp": {
"command": "npx",
"args": ["-y", "@gmag11/nodered-mcp-server", "--transport=stdio"],
"env": {
"HOME": "/home/your-user",
"NODERED_URL": "http://localhost:1880",
"NODERED_API_KEY": "your-api-key"
}
}
}
}
```
## 许可证
Apache-2.0
