🚀 MCP Node-RED Server

A modern, production-ready Model Context Protocol (MCP) server for Node-RED integration.

🌟 Features

🔧 20 MCP Tools

Full CRUD for flows, context variables, modules, and diagnostics — plus semantic search and real-time error detection.

📚 Prompts Library

Built-in prompt templates: debug_flow, explain_automation, audit_security, document_flow.

📦 MCP Resources

Browse Node-RED state as structured resources: nodered://flows, nodered://subflows, nodered://nodes, nodered://context/global, flow://<id>, system://runtime.

🔍 Semantic Search

Embeddings-based search across flows and nodes via semantic_search_flows. Finds by meaning, not just keywords.

🧠 Elicitation

The server asks clarifying questions mid-call when required parameters are missing (MCP SDK 1.24+ elicitation).

🚨 Real-time Error Detection

get_node_errors connects to Node-RED's WebSocket /comms endpoint to detect nodes in error/warning state in real time.

Related MCP server: MCP Server for n8n Integration

📋 Table of Contents

• Quick Start

• Available Tools

• Read-Only Mode

• Resources

• Prompts

• Connecting

• Node-RED Authentication

• Environment Variables

⚡ Quick Start

Prerequisites

• Node.js 22+ (LTS recommended)

• Yarn 4.x (automatically managed via Corepack)

• Docker (optional, for containerized setup)

Native Installation

git clone https://github.com/ziv-daniel/node-red-mcp.git
cd node-red-mcp
yarn install
yarn build

Docker

docker run -e NODERED_URL=http://your-nodered:1880 \
           -e NODERED_USERNAME=admin \
           -e NODERED_PASSWORD=password \
           -p 3000:3000 \
           ghcr.io/ziv-daniel/node-red-mcp:latest

🔧 Available MCP Tools

Flow Management

Context Variables

Modules

Diagnostics

🔒 Read-Only Mode

Set MCP_READ_ONLY=true to structurally prevent any mutation of your Node-RED flows — useful when exposing this server to remote AI agents where an accidental or unintended write to a live/production instance is a real risk.

When enabled, write tools (create_flow, update_flow, delete_flow, enable_flow, disable_flow, set_context, delete_context, install_module) are removed from the tool list entirely — clients never see them as available capabilities — and are also rejected if called directly by name. All read, search, diagnostic, resource, and prompt capabilities remain fully available. This pairs naturally with delete_flow's existing dryRun default for deployments that need read/write in the same session but still want an extra layer of protection against accidental writes.

📦 MCP Resources

Access Node-RED state as browseable MCP resources:

📚 MCP Prompts

Built-in prompt templates for common tasks:

🔌 Connecting to the Server

Transport Modes

Authentication

Set MCP_USERNAME and MCP_PASSWORD for HTTP Basic Auth on the /mcp endpoint.

Claude Desktop (stdio)

{
  "mcpServers": {
    "nodered": {
      "command": "node",
      "args": ["path/to/node-red-mcp/dist/index.mjs"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "NODERED_URL": "https://your-nodered-instance.com",
        "NODERED_USERNAME": "admin",
        "NODERED_PASSWORD": "password"
      }
    }
  }
}

Claude Code / Remote Agent (HTTP)

claude mcp add node-red \
  --transport streamable-http \
  --url https://<your-server>/mcp \
  --header "Authorization: Basic <base64-credentials>"

Node-RED Authentication

NODERED_USERNAME/NODERED_PASSWORD mean one of two different things depending on your deployment, and this server needs to know which:

• Node-RED's own adminAuth is enabled — these are Node-RED's own admin credentials. Set NODERED_ADMIN_AUTH_ENABLED=true and the server exchanges them for a Bearer token via Node-RED's /auth/token password grant on first use (Node-RED's admin API only accepts Bearer tokens, not HTTP Basic auth — this is required, not optional, in this mode). The token is cached in memory and transparently re-exchanged shortly before it expires (or immediately after a 401). You never see the token. The same in-band exchange also authenticates the /comms WebSocket used by get_node_errors, since Node-RED's WebSocket auth is its own separate in-band handshake, not header-based.

• The credentials belong to something in front of Node-RED — e.g. an nginx or Traefik Basic-auth layer gating every request to the whole instance, unrelated to Node-RED's own auth. Leave NODERED_ADMIN_AUTH_ENABLED unset (the default). The server sends a static HTTP Basic header built from NODERED_USERNAME/NODERED_PASSWORD on every request, including the WebSocket upgrade — exactly what a proxy in this position expects, and exactly what Node-RED's own admin API would reject if its adminAuth were enabled.

Alternatively, NODERED_API_TOKEN supplies an already-issued Node-RED bearer token directly (e.g. one you obtained yourself via /auth/token). Useful if you don't want this server to hold your Node-RED password, at the cost of having to refresh the token yourself once it expires. This mode is unaffected by NODERED_ADMIN_AUTH_ENABLED.

If none of these are set, requests are sent unauthenticated — only appropriate when Node-RED's adminAuth is disabled and nothing sits in front of the instance either.

Known limitation: these two topologies are mutually exclusive today. If you genuinely run both — a reverse-proxy Basic-auth layer in front of an instance that also has Node-RED's own adminAuth enabled — there's currently no way to supply separate credentials for each; NODERED_USERNAME/PASSWORD can only be exchanged for a token or sent as a static Basic header, not both at once for two different recipients. Supporting that would need a second, distinct credential pair sent independently of the Bearer exchange.

⚙️ Environment Variables

Running Behind a Reverse Proxy

Express ignores X-Forwarded-For unless you tell it which proxies to trust. Left unset behind a proxy, every client resolves to the proxy's own address and shares a single rate-limit bucket. TRUST_PROXY sets Express's trust proxy:

Use the hop count wherever you can: TRUST_PROXY=1 for a single Traefik, nginx or Caddy in front, TRUST_PROXY=2 for something like Traefik in front of Pomerium. Count the proxies that actually append to X-Forwarded-For.

TRUST_PROXY=true is accepted, but the server logs a warning on startup and express-rate-limit reports it as ERR_ERL_PERMISSIVE_TRUST_PROXY. Trusting every hop means any client can spoof its address — and so its rate-limit bucket — just by sending its own X-Forwarded-For header. Prefer a hop count or an explicit trust list.