Nr MCP

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:

Why not just use the existing MCP servers?

• Tab reorder bug: Other implementations use PUT /flow/:id which silently reorders your tabs in Node-RED. nr-mcp uses the correct GET → POST /flows full-deploy pattern.
• Optimistic locking: Every deploy checks the rev field. 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).

Installation

Prerequisites

• Python 3.11+
• uv (recommended) or pip
• Node-RED instance with Admin API enabled

Install from PyPI

pip install nr-mcp

Install with uv (recommended)

uv tool install nr-mcp

Or 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

\* 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:

`bash

#!/bin/bash

cd /tmp

exec nr-mcp "$@"

`

Then point command to 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 API

Key design decisions

• GET→POST pattern: All deploys fetch full flows, modify in-place, then POST back. Never uses PUT /flow/:id which reorders tabs.
• Optimistic locking: Uses the Node-RED rev field 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 /flows and POST /flows — flow read/write
• GET /context/flow/:id — flow context
• POST /inject/:id — inject trigger
• GET /nodes and POST /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.