README
¶
nodered-mcp
An MCP (Model Context Protocol) server, written in Go, that exposes the Node-RED admin API to AI clients as tools, resources, and prompts.
flowchart LR
client["MCP client<br/>(Claude, Cursor, …)"]
server["nodered-mcp<br/>(this binary)"]
nr["Node-RED :1880"]
client -- "stdio / HTTP" --> server
server -- "HTTP" --> nr
nodered-mcp is provider-agnostic. The same binary works with any
MCP-capable client — Claude Desktop, Claude Code, Cursor, VS Code,
Gemini CLI, OpenCode, Pi, Cline — regardless of the underlying
model.
A Spanish version of this document is available at
README.es.md.
Install
Three channels are supported. Pick the one that fits:
# npm — works on every platform. Recommended.
npm install -g @fgjcarlos/nodered-mcp
# go install — for anyone with a Go toolchain.
go install github.com/fgjcarlos/nodered-mcp/cmd/nodered-mcp@latest
# Docker — the binary runs inside the image; restart by replacing the container.
docker pull ghcr.io/fgjcarlos/nodered-mcp:latest
After install, generate the snippet for your MCP client:
# 2. Generate the snippet for your MCP client
nodered-mcp init --write
# 3. Restart your MCP client; 44 tools appear under the "nodered" server
Need help? See docs/troubleshooting.md.
Documentation
The full reference lives in docs/:
| Doc | Covers |
|---|---|
docs/architecture.md |
Source tree, dependencies, JSON-opaque flow model, backup-before-write guardrail |
docs/tools.md |
Catalog of the 44 MCP tools (read / write / action) |
docs/configuration.md |
Environment variables and command-line flags |
docs/transports.md |
stdio and streamable HTTP transports, bearer auth, OAuth 2.1 |
docs/clients.md |
Per-MCP-client configuration snippets |
docs/troubleshooting.md |
Common failure modes and how to recover |
docs/roadmap.md |
Open work, accepted risks, planned versions |
Safety
Handing an LLM write access to a running automation runtime demands guardrails. Three are built in:
- Flow documents are treated as opaque JSON — no fixed Go structs, no field loss.
- Every mutating operation takes a backup of the full flow configuration first and fails closed if the snapshot cannot be written.
- Wires are validated before the write reaches the runtime; dangling wire targets are rejected at the MCP layer.
Run with --read-only (or MCP_READ_ONLY=true) to advertise only
the 21 read tools and withhold every mutating one at registration.
inject_node is also withheld: firing an inject can send a real
command to real hardware.
Full threat model and hardening checklist:
SECURITY.md.
Development
go test ./...
go build -o nodered-mcp ./cmd/nodered-mcp
Work items live as GitHub Issues. Design decisions and historical
audit reports live under docs/. See
CONTRIBUTING.md for the workflow.
License
MIT. See LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
nodered-mcp
command
Command nodered-mcp is an MCP (Model Context Protocol) server that exposes a Node-RED instance to LLM clients such as Claude Desktop.
|
Command nodered-mcp is an MCP (Model Context Protocol) server that exposes a Node-RED instance to LLM clients such as Claude Desktop. |
|
internal
|
|
|
config
Package config loads runtime configuration from environment variables.
|
Package config loads runtime configuration from environment variables. |
|
mcp
Package mcp wires up the Model Context Protocol server.
|
Package mcp wires up the Model Context Protocol server. |
|
nodered
Package nodered is a thin client for the Node-RED admin HTTP API.
|
Package nodered is a thin client for the Node-RED admin HTTP API. |
|
oauth
Package oauth validates bearer tokens issued by an external OAuth 2.1 / OpenID Connect identity provider.
|
Package oauth validates bearer tokens issued by an external OAuth 2.1 / OpenID Connect identity provider. |