nr-mcp

nr-mcp

一个 Model Context Protocol（MCP）服务，可让 AI 助手与 Node-RED 交互——读取流程、搜索节点、编辑函数代码、安全部署更改并管理模块。

它旨在解决实际问题：现有的 Node-RED MCP 实现使用 PUT /flow/:id，这会重新排列你的选项卡。nr-mcp 使用正确的 GET → POST /flows 模式，并采用乐观锁定，因此选项卡顺序始终保持不变。

功能

13 个工具，用于全面管理 Node-RED 流程：

工具	描述
nr_get_flow_summary	概览所有选项卡，包括节点数量和分组
nr_get_flow	获取单个选项卡及其所有节点——按名称或 ID
nr_search_nodes	按名称、类型或 JavaScript 代码内容搜索节点
nr_get_function_code	提取函数节点的完整 JS 代码（包括 init/finalize）
nr_get_node_config	完整配置，以及计算得出的上游/下游连接
nr_get_flow_context	读取流程级别的上下文变量
nr_safe_deploy	使用乐观锁定部署更改——绝不重新排列选项卡
nr_create_nodes	在一次部署中批量创建节点/分组
nr_delete_nodes	批量删除，并自动清理连线和分组
nr_inject	远程触发 inject 节点以测试流程
nr_get_installed_modules	列出已安装模块和可用节点类型
nr_install_module	从 Node-RED 注册表安装 npm 包
nr_get_debug_output	从流程上下文读取调试/错误数据

为什么不直接使用现有的 MCP 服务？

• 选项卡重排问题：其他实现使用 PUT /flow/:id，会在 Node-RED 中悄悄重新排列选项卡。nr-mcp 使用正确的 GET → POST /flows 全量部署模式。
• 乐观锁定：每次部署都会检查 rev 字段。如果其他人在你读取和写入之间进行了部署，你会收到明确的冲突错误，而不是数据悄然丢失。
• 智能搜索：一次调用即可搜索节点名称、类型、函数代码、模板和操作。
• 经过生产环境验证：为管理复杂的 Node-RED 安装环境（家庭自动化、IoT、能源管理）而构建，并在日常使用。

安装

前置条件

• Python 3.11+
• uv（推荐）或 pip
• 已启用 Admin API 的 Node-RED 实例

从 PyPI 安装

pip install nr-mcp

使用 uv 安装（推荐）

uv tool install nr-mcp

或从源代码安装：

git clone https://github.com/Texan-NXTassist/nr-mcp.git
cd nr-mcp
uv tool install .

这会在 ~/.local/bin/ 中创建 nr-mcp 命令。

配置

环境变量

变量	必填	描述
NR_URL	否	Node-RED URL（默认：http://localhost:1880）
NR_TOKEN	否*	基于令牌的身份验证所用的 Bearer token
NR_USER	否*	Basic Auth 用户名
NR_PASS	否*	Basic Auth 密码

* 建议至少配置一种身份验证方式。身份验证按以下顺序检查：令牌 → Basic Auth → 无身份验证。

Claude Desktop

添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "nr-mcp": {
      "command": "nr-mcp",
      "env": {
        "NR_URL": "http://localhost:1880",
        "NR_USER": "admin",
        "NR_PASS": "your-password"
      }
    }
  }
}

提示：如果遇到“工作目录”错误，请创建一个包装脚本：

#!/bin/bash
cd /tmp
exec nr-mcp "$@"

然后将 command 指向包装脚本的路径。

Cursor / VS Code

添加到你的 MCP 设置中（.cursor/mcp.json 或 VS Code 对应的配置文件）：

{
  "mcpServers": {
    "nr-mcp": {
      "command": "nr-mcp",
      "env": {
        "NR_URL": "http://localhost:1880",
        "NR_TOKEN": "your-access-token"
      }
    }
  }
}

使用示例

连接后，你可以向 AI 助手提出以下请求：

• “显示所有 Node-RED 选项卡及其节点数量”
• “搜索代码中包含 'mqtt' 的节点”
• “显示节点 abc123 的函数代码”
• “更新节点 xyz 中的函数代码，加入错误处理”
• “在 Weather 选项卡上创建一个 inject 节点和一个 HTTP request 节点”
• “安装了哪些模块？node-red-dashboard 是否可用？”
• “安装 node-red-contrib-influxdb”
• “触发名为 'Test' 的 inject 节点，并检查是否有错误”

架构

nr-mcp 是一个 Python MCP 服务，通过其 Admin API 与 Node-RED 通信。它使用 stdio 传输（MCP 的标准方式），并向你的 Node-RED 实例发起 HTTP 请求。

AI Assistant ↔ MCP (stdio) ↔ nr-mcp ↔ HTTP ↔ Node-RED Admin API

关键设计决策

• GET→POST 模式：所有部署都会获取完整流程，在原处修改，然后再 POST 回去。绝不会使用 PUT /flow/:id，因为这会重新排序选项卡。
• 乐观锁：使用 Node-RED 的 rev 字段检测并发修改。
• 不缓存：每次工具调用都会获取最新数据。速度稍慢，但始终准确。
• 冲突时仅重试一次：部署操作在遇到 409 Conflict 时会重试一次。

更多详情请参阅 docs/ARCHITECTURE.md。

Node-RED 设置

Admin API 必须启用（默认已启用）。如果你限制了该 API，请确保以下端点可访问：

• GET /flows 和 POST /flows — 流程读写
• GET /context/flow/:id — 流程上下文
• POST /inject/:id — 注入触发器
• GET /nodes 和 POST /nodes — 模块管理

有关身份验证配置，请参阅 Node-RED Admin API docs。

贡献

欢迎贡献！请先提交 issue，讨论你想要进行的更改。

git clone https://github.com/Texan-NXTassist/nr-mcp.git
cd nr-mcp
uv venv && source .venv/bin/activate
uv pip install -e .

许可证

MIT — 请参阅 LICENSE。