🚀 MCP Node-RED Server

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

🌟 Features

🚀 Architecture

• Node.js 22 LTS with latest JavaScript features

• TypeScript 5.7+ with strict type checking

• ESM-first with dual ESM/CJS output using tsup

• Yarn 4 with zero-installs and modern package management

🔄 Node-RED Integration

• Node-RED v4 support with latest features

• Real-time flow monitoring via SSE

• Template flows for common MCP patterns

• Admin API integration for flow management

• WebSocket support for live updates

🛡️ Reliability & Resilience (2025 Updates)

• Circuit Breaker Pattern for fault tolerance

• Exponential Backoff Retry with smart failure handling

• Request Timeout Management with proper cleanup

• Server Discovery via .well-known/mcp.json (November 2025 spec)

• MCP SDK 1.22.0 with latest protocol enhancements

• Comprehensive Error Handling with 19 test cases

📊 Observability

• Structured Logging with Pino

• Circuit Breaker Metrics and health monitoring

• Request Correlation IDs for debugging

• Performance Metrics collection

📋 Table of Contents

• Quick Start

• Installation

• Usage

⚡ Quick Start

Prerequisites

• Node.js 22+ (LTS recommended)

• Yarn 4.x (automatically managed via Corepack)

• Claude Desktop or other MCP client (for stdio mode)

• Docker & Docker Compose (optional, for containerized setup)

🚀 Option 1: Native Installation (For Claude Desktop)

# Clone the repository
git clone https://github.com/your-org/nodered-mcp.git
cd nodered-mcp

# Install dependencies (Yarn 4 will be automatically used)
yarn install

# Build the project (no .env file needed for stdio mode)
yarn build

# Test the server (optional)
echo '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}},"id":1}' | node dist/index.mjs

# Configure in Claude Desktop (see Usage section)

🐳 Option 2: Docker Compose (For HTTP Mode Development)

# Clone and start the full stack
git clone https://github.com/your-org/nodered-mcp.git
cd nodered-mcp

# Start all services (includes Node-RED, PostgreSQL, Redis, monitoring)
docker-compose up -d

# View logs
docker-compose logs -f mcp-server

Access the services:

• MCP Server: http://localhost:3000

• Node-RED: http://localhost:1880

• Grafana: http://localhost:3001 (admin/admin)

• Jaeger: http://localhost:16686

🔧 Installation

System Requirements

• Node.js: 22.0.0 or higher

• Memory: 512MB minimum, 2GB recommended

• Storage: 1GB available space

Local Development Setup

# Enable Corepack (if not already enabled)
corepack enable

# Verify versions
node --version  # Should be 22.x.x
yarn --version  # Should be 4.x.x

# Install dependencies
yarn install

# Set up environment
cp env.example .env
# Edit .env file with your configuration

# Run in development mode with hot reload
yarn dev

🎯 Usage

Claude Desktop Integration (Recommended)

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "nodered": {
      "command": "node",
      "args": ["path/to/nodered_mcp/dist/index.mjs"],
      "env": {
        "NODERED_URL": "https://your-nodered-instance.com",
        "NODERED_USERNAME": "your-username",
        "NODERED_PASSWORD": "your-secure-password"
      }
    }
  }
}

Available MCP Tools

🔌 Connecting to the Server

The MCP server supports multiple transport modes and authentication methods. Choose the one that fits your setup.

Transport Modes

Authentication

The server supports two authentication methods (configured via environment variables):

1. HTTP Basic Auth — Set MCP_USERNAME and MCP_PASSWORD. Clients send an Authorization: Basic <base64> header.

2. Bearer Token (JWT) — After authenticating, clients receive a JWT for subsequent requests. Requires JWT_SECRET to be set.

Connecting via Streamable HTTP (Remote)

For remote MCP clients (Claude Code, custom agents, etc.), point them to the /mcp endpoint:

# Generic connection parameters
URL: https://<your-server-host>/mcp
Transport: streamable-http
Auth header: Authorization: Basic <base64(username:password)>

Claude Code CLI example:

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

Connecting via Stdio (Local)

For Claude Desktop or other local MCP hosts, use stdio mode:

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

Environment Variables