nodered-mcp

A Python MCP server for Node-RED flow management, built on FastMCP and Pydantic.

Gives language models full read/write access to a Node-RED instance through the Admin HTTP API, with structured Pydantic responses, incremental flow patching, layout linting, and flexible authentication (token, basic, OAuth2).

Compared to node-red-mcp-server

This project was inspired by karavaev-evgeniy/node-red-mcp-server (TypeScript/npm). Key differences:

Related MCP server: n8n-MCP

Installation

Requires Python 3.11+ and uv:

git clone <repo-url> && cd nodered-mcp
uv sync

Quick Start

# Minimal — token auth (default)
export NODE_RED_URL=http://localhost:1880
export NODE_RED_TOKEN=your-api-token
uv run nodered-mcp

Configuration

All configuration is via environment variables with the NODE_RED_ prefix.

Authentication

Token (default)

Static bearer token sent with every request. This is the simplest method and matches how node-red-mcp-server works:

NODE_RED_URL=http://localhost:1880
NODE_RED_TOKEN=your-api-token

Basic Auth

HTTP Basic authentication, useful when Node-RED sits behind a forward auth proxy.

NODE_RED_AUTH_METHOD=basic
NODE_RED_AUTH_USERNAME=admin
NODE_RED_AUTH_PASSWORD=your-password

Basic Auth with Authentik

If your Node-RED instance sits behind Authentik as a forward auth proxy, the basic auth method works well. Authentik intercepts requests, validates credentials, and sets session cookies before forwarding to Node-RED.

1. Create an Authentik application for your Node-RED instance using the Forward Auth (single application) provider.

2. Configure your reverse proxy (Traefik, nginx, Caddy) to use Authentik's forward auth endpoint. For example, with Traefik:

   # docker-compose.yml (Traefik labels on the Node-RED service)
   labels:
     - "traefik.http.routers.nodered.middlewares=authentik@docker"

3. Create an Authentik service account (or use an existing user) and generate an app password under the user's token settings. This avoids MFA prompts that would block API access.

4. Configure nodered-mcp:

   NODE_RED_URL=https://nodered.yourdomain.com
   NODE_RED_AUTH_METHOD=basic
   NODE_RED_AUTH_USERNAME=service-account
   NODE_RED_AUTH_PASSWORD=the-app-password-from-authentik

The basic auth credentials are sent to Authentik's proxy, which validates them and sets cookies. Subsequent requests use the session cookie, so Node-RED itself doesn't need auth enabled.

OAuth2 Client Credentials

Fetches a short-lived JWT via OAuth2 client credentials grant. The token is cached and auto-refreshed with a 30-second expiry buffer. On a 401 response, the server retries once with a fresh token.

Works with Authentik out of the box — every application has a token endpoint and client_id:

NODE_RED_AUTH_METHOD=oauth
NODE_RED_AUTH_USERNAME=service-account
NODE_RED_AUTH_PASSWORD=service-password
NODE_RED_OAUTH_TOKEN_URL=https://auth.yourdomain.com/application/o/token/
NODE_RED_OAUTH_CLIENT_ID=your-client-id

MCP Client Configuration

Claude Desktop

{
  "mcpServers": {
    "nodered": {
      "command": "uv",
      "args": ["--directory", "/path/to/nodered-mcp", "run", "nodered-mcp"],
      "env": {
        "NODE_RED_URL": "http://localhost:1880",
        "NODE_RED_TOKEN": "your-token"
      }
    }
  }
}

Claude Code

{
  "mcpServers": {
    "nodered": {
      "command": "uv",
      "args": ["--directory", "/path/to/nodered-mcp", "run", "nodered-mcp"],
      "env": {
        "NODE_RED_URL": "http://localhost:1880",
        "NODE_RED_TOKEN": "your-token"
      }
    }
  }
}

Tools

Flow Tools (12)

Node Tools (6)

Layout Tools (1)

Settings Tools (2)

Utility Tools (1)

Architecture

src/nodered_mcp/
├── server.py              # FastMCP server, config, client init
├── config.py              # Pydantic Settings (env vars)
├── client.py              # Async httpx wrapper with auth
├── models/
│   ├── base.py            # BaseApiModel with from_api()
│   ├── flow.py            # Node, FlowTab, Flow, FlowState
│   ├── node.py            # NodeModule, NodeSet
│   ├── responses.py       # FlowList, FlowSummary, Settings, etc.
│   └── layout.py          # LayoutIssue, LayoutReport
└── tools/
    ├── flows.py           # Flow CRUD + patch + auto-lint
    ├── nodes.py           # Node management + search
    ├── layout.py          # Layout lint checks
    ├── settings.py        # Settings + diagnostics
    └── utility.py         # API help reference

The layer diagram is simple:

MCP Tools (thin async functions, return Pydantic models)
  ↓
NodeRedClient (async httpx, returns raw dicts)
  ↓
Node-RED Admin HTTP API

Development

make all              # format + lint + test
make check            # lint + test (no format)
make test             # uv run pytest tests/ -v
make lint             # uv run ruff check src/ tests/
make format           # uv run ruff format src/ tests/

Run a single test file:

uv run pytest tests/tools/test_layout.py -v

Run with coverage:

uv run pytest tests/ -v --cov=src/nodered_mcp --cov-report=term-missing

Always use uv run — never bare python or pytest.

See conventions.md for detailed code patterns (model layering, tool conventions, client architecture).

License

MIT