nr-mcp
Allows AI assistants to interact with Node-RED for flow management, including reading flows, searching nodes, editing function code, deploying changes safely, and managing modules via the Node-RED Admin API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@nr-mcp Show me the summary of all flows"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
nr-mcp
A Model Context Protocol (MCP) server that lets AI assistants interact with Node-RED — read flows, search nodes, edit function code, deploy changes safely, and manage modules.
Built to solve real problems: the existing Node-RED MCP implementations use PUT /flow/:id which reorders your tabs. nr-mcp uses the correct GET → POST /flows pattern with optimistic locking, so your tab order is always preserved.
Features
13 tools for complete Node-RED flow management:
Tool | Description |
| Overview of all tabs with node counts and groups |
| Get a single tab with all nodes — by name or ID |
| Search nodes by name, type, or JavaScript code content |
| Extract full JS code from function nodes (incl. init/finalize) |
| Full config with computed upstream/downstream connections |
| Read flow-level context variables |
| Deploy changes with optimistic locking — never reorders tabs |
| Batch-create nodes/groups in a single deploy |
| Batch-delete with automatic wire and group cleanup |
| Trigger inject nodes remotely to test flows |
| List installed modules and available node types |
| Install npm packages from the Node-RED registry |
| Read debug/error data from flow context |
Why not just use the existing MCP servers?
Tab reorder bug: Other implementations use
PUT /flow/:idwhich silently reorders your tabs in Node-RED. nr-mcp uses the correctGET → POST /flowsfull-deploy pattern.Optimistic locking: Every deploy checks the
revfield. If someone else deployed between your read and write, you get a clear conflict error instead of silent data loss.Smart search: Search across node names, types, function code, templates, and actions in one call.
Production-tested: Built and used daily for managing complex Node-RED installations (home automation, IoT, energy management).
Related MCP server: node-red-contrib-mcp-server
Installation
Prerequisites
Install from PyPI
pip install nr-mcpInstall with uv (recommended)
uv tool install nr-mcpOr from source:
git clone https://github.com/Texan-NXTassist/nr-mcp.git
cd nr-mcp
uv tool install .This creates the nr-mcp command in ~/.local/bin/.
Configuration
Environment variables
Variable | Required | Description |
| No | Node-RED URL (default: |
| No* | Bearer token for token-based auth |
| No* | Username for Basic Auth |
| No* | Password for Basic Auth |
* At least one auth method is recommended. Auth is checked in order: token → basic auth → no auth.
Claude Desktop
Add to your claude_desktop_config.json:
{
"mcpServers": {
"nr-mcp": {
"command": "nr-mcp",
"env": {
"NR_URL": "http://localhost:1880",
"NR_USER": "admin",
"NR_PASS": "your-password"
}
}
}
}Tip: If you get a "working directory" error, create a wrapper script:
#!/bin/bash cd /tmp exec nr-mcp "$@"Then point
commandto the wrapper path.
Cursor / VS Code
Add to your MCP settings (.cursor/mcp.json or VS Code equivalent):
{
"mcpServers": {
"nr-mcp": {
"command": "nr-mcp",
"env": {
"NR_URL": "http://localhost:1880",
"NR_TOKEN": "your-access-token"
}
}
}
}Usage examples
Once connected, you can ask your AI assistant things like:
"Show me all Node-RED tabs and their node counts"
"Search for nodes that contain 'mqtt' in their code"
"Show me the function code for node abc123"
"Update the function code in node xyz to add error handling"
"Create an inject node and an HTTP request node on the Weather tab"
"What modules are installed? Is node-red-dashboard available?"
"Install node-red-contrib-influxdb"
"Trigger the 'Test' inject node and check for errors"
Architecture
nr-mcp is a Python MCP server that communicates with Node-RED via its Admin API. It uses stdio transport (standard for MCP) and makes HTTP calls to your Node-RED instance.
AI Assistant ↔ MCP (stdio) ↔ nr-mcp ↔ HTTP ↔ Node-RED Admin APIKey design decisions
GET→POST pattern: All deploys fetch full flows, modify in-place, then POST back. Never uses
PUT /flow/:idwhich reorders tabs.Optimistic locking: Uses the Node-RED
revfield to detect concurrent modifications.No caching: Every tool call fetches fresh data. Slightly slower, but always correct.
Single retry on conflict: Deploy operations retry once on 409 Conflict.
For more details, see docs/ARCHITECTURE.md.
Node-RED setup
The Admin API must be enabled (it is by default). If you've restricted it, ensure these endpoints are accessible:
GET /flowsandPOST /flows— flow read/writeGET /context/flow/:id— flow contextPOST /inject/:id— inject triggerGET /nodesandPOST /nodes— module management
See Node-RED Admin API docs for auth configuration.
Contributing
Contributions welcome! Please open an issue first to discuss what you'd like to change.
git clone https://github.com/Texan-NXTassist/nr-mcp.git
cd nr-mcp
uv venv && source .venv/bin/activate
uv pip install -e .License
MIT — see LICENSE.
Available Tools
13 toolsnr_create_nodesA
Create one or more new nodes/groups in a single deploy. Each node dict must include 'id', 'type', and 'z' (target tab ID). Groups need 'type': 'group'. Config nodes (e.g. ha-entity-config) use 'z': '' for global scope.
Inputs: nodes (required), description. Returns: result
nr_delete_nodesA
Delete one or more nodes by ID. Also cleans up references: removes deleted IDs from group.nodes arrays and from other nodes' wires arrays.
Inputs: node_ids (required), description. Returns: result
nr_get_debug_outputA
Read debug output from flow context. Use when a flow has a catch node that stores errors/debug data to flow context. Pass key=null to list all context keys. Trigger flow with nr_inject first, then read this.
Inputs: flow_id (required), key. Returns: result
nr_get_flowA
Get a single Node-RED tab with all its nodes and groups. Accepts tab name (case-insensitive) or tab ID.
Inputs: name_or_id (required). Returns: result
nr_get_flow_contextA
Read Node-RED flow context variables. Pass key=null to list all keys, or a specific key to get its value.
Inputs: flow_id (required), key. Returns: result
nr_get_flow_summaryA
Quick overview of all Node-RED tabs with node counts and groups.
Inputs: no named parameters. Returns: result
nr_get_function_codeB
Extract full JavaScript code from a Node-RED function node.
Inputs: node_id (required). Returns: result
nr_get_installed_modulesA
List installed Node-RED modules and their node types. Optionally filter by module name or node type containing query string. Returns module name, version, and list of node types provided.
Inputs: query. Returns: result
nr_get_node_configB
Get full node configuration including wires, upstream/downstream connections, and group membership.
Inputs: node_id (required). Returns: result
nr_injectA
Trigger an inject node to fire immediately. Use nr_search_nodes to find inject nodes first. The node must be of type 'inject'.
Inputs: node_id (required). Returns: result
nr_install_moduleA
Install a new Node-RED module (npm package) from the registry. Use nr_get_installed_modules to check what's already installed first. Installation may take 30-60 seconds.
Inputs: module_name (required). Returns: result
nr_safe_deployB
Deploy changes to a Node-RED node with optimistic locking. Uses correct GET→POST pattern (never PUT). Preserves tab order.
Inputs: node_id (required), fields (required), description. Returns: result
nr_search_nodesC
Search Node-RED nodes by name, type, or function code content. Searches in: name, type, func, template, action fields.
Inputs: query (required), type, flow, max_results. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Each tool targets a distinct operation: creation, deletion, retrieval of various aspects (flow, config, code, context, summary), searching, injecting, module management, and deployment. No two tools have overlapping functionality due to clear scope definitions.
All tools follow the 'nr_verb_noun' pattern with consistent snake_case naming. Verbs are descriptive (create, delete, get, inject, install, safe_deploy, search) and nouns clearly indicate the resource or action.
13 tools cover the core Node-RED management operations without being excessive. The count is well-scoped for typical use cases including node manipulation, flow inspection, module management, and deployment.
The tool set covers CRUD for nodes and flows, searching, debugging, module installation, and deployment. Minor gaps exist (e.g., no explicit tool to update individual node properties, no module uninstall), but the deployment tool and context operations mitigate these for most workflows.
Maintenance
Related MCP Connectors
Manage NodePal Minecraft servers, worlds, mods, backups and console from AI agents.
Inspect and control your Northflank projects, services, jobs, and builds from your AI assistant.
Generate, inspect, and manage Flowstep UI designs directly from your AI assistant.
Create and edit flows, read responses, and reply to users — from your AI assistant.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceA Model Context Protocol server for Node-RED integration, enabling AI agents to manage flows, install modules, and monitor Node-RED instances via natural language.6MIT
- AlicenseNot gradedqualityBmaintenanceExposes Node-RED flows as MCP tools for AI assistants, with OAuth protection and optional admin tools for flow management.113 npm2ISC
- AlicenseBqualityDmaintenanceConnects AI assistants to the Node-RED Admin API, enabling flow inspection, node management, graph analysis, debug capture, and rollback operations through natural language.37MIT
- AlicenseNot gradedqualityBmaintenanceTurns Node-RED flows into OAuth-protected MCP tools that AI assistants can call, with optional read-only access to the Node-RED admin API.381 npmMIT