Skip to main content
Glama

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

nr_get_flow_summary

Overview of all tabs with node counts and groups

nr_get_flow

Get a single tab with all nodes — by name or ID

nr_search_nodes

Search nodes by name, type, or JavaScript code content

nr_get_function_code

Extract full JS code from function nodes (incl. init/finalize)

nr_get_node_config

Full config with computed upstream/downstream connections

nr_get_flow_context

Read flow-level context variables

nr_safe_deploy

Deploy changes with optimistic locking — never reorders tabs

nr_create_nodes

Batch-create nodes/groups in a single deploy

nr_delete_nodes

Batch-delete with automatic wire and group cleanup

nr_inject

Trigger inject nodes remotely to test flows

nr_get_installed_modules

List installed modules and available node types

nr_install_module

Install npm packages from the Node-RED registry

nr_get_debug_output

Read debug/error data from flow context

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).

Related MCP server: node-red-contrib-mcp-server

Installation

Prerequisites

  • Python 3.11+

  • uv (recommended) or pip

  • Node-RED instance with Admin API enabled

Install from PyPI

pip install nr-mcp
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

Variable

Required

Description

NR_URL

No

Node-RED URL (default: http://localhost:1880)

NR_TOKEN

No*

Bearer token for token-based auth

NR_USER

No*

Username for Basic Auth

NR_PASS

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 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.

Available Tools

13 tools
nr_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

    A3.8/5.0

    Scored across 13 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      A Model Context Protocol server for Node-RED integration, enabling AI agents to manage flows, install modules, and monitor Node-RED instances via natural language.
      6
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Connects AI assistants to the Node-RED Admin API, enabling flow inspection, node management, graph analysis, debug capture, and rollback operations through natural language.
      37
      MIT