🚀 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

• 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>"

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