io.github.Texan-NXTassist/nr-mcp
MCP server for Node-RED — safe deploy, optimistic locking, smart search, 13 tools
Open source Open in the app JSON README (API)
About
MCP server for Node-RED — safe deploy, optimistic locking, smart search, 13 tools
Details
- Kind
- MCP servers
- Topic
- Cloud & DevOps
- Publisher
- texan-nxtassist
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.2.2
- Stars
- 1
- Forks
- 4
- Open pull requests
- 2
- Last push
- 2026-03-25T22:56:09Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 03:02:16
- Updated
- 2026-08-29 03:02:16
- Origin id
io.github.Texan-NXTassist/nr-mcp
README
# nr-mcp
<!-- mcp-name: io.github.Texan-NXTassist/nr-mcp -->
A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that lets AI assistants interact with [Node-RED](https://nodered.org) — read flows, search nodes, edit function code, deploy changes safely, and manage modules.
Built to solve real problems: the existing Node-RED MCP implementations use `PUT /flow/:id` which **reorders your tabs**. nr-mcp uses the correct `GET → POST /flows` pattern with optimistic locking, so your tab order is always preserved.
## Features
**13 tools** for complete Node-RED flow management:
| Tool | Description |
|------|-------------|
| `nr_get_flow_summary` | Overview of all tabs with node counts and groups |
| `nr_get_flow` | Get a single tab with all nodes — by name or ID |
| `nr_search_nodes` | Search nodes by name, type, or JavaScript code content |
| `nr_get_function_code` | Extract full JS code from function nodes (incl. init/finalize) |
| `nr_get_node_config` | Full config with computed upstream/downstream connections |
| `nr_get_flow_context` | Read flow-level context variables |
| `nr_safe_deploy` | Deploy changes with optimistic locking — **never reorders tabs** |
| `nr_create_nodes` | Batch-create nodes/groups in a single deploy |
| `nr_delete_nodes` | Batch-delete with automatic wire and group cleanup |
| `nr_inject` | Trigger inject nodes remotely to test flows |
| `nr_get_installed_modules` | List installed modules and available node types |
| `nr_install_module` | Install npm packages from the Node-RED registry |
| `nr_get_debug_output` | Read debug/error data from flow context |
### Why not just use the existing MCP servers?
- **Tab reorder bug**: Other implementations use `PUT /flow/:id` which silently reorders your tabs in Node-RED. nr-mcp uses the correct `GET → POST /flows` full-deploy pattern.
- **Optimistic locking**: Every deploy checks the `rev` field. If someone else deployed between your read and write, you get a clear conflict error instead of silent data loss.
- **Smart search**: Search across node names, types, function code, templates, and actions in one call.
- **Production-tested**: Built and used daily for managing complex Node-RED installations (home automation, IoT, energy management).
## Installation
### Prerequisites
- Python 3.11+
- [uv](https://docs.astral.sh/uv/) (recommended) or pip
- Node-RED instance with [Admin API](https://nodered.org/docs/api/admin/) enabled
### Install from PyPI
```bash
pip install nr-mcp
```
### Install with uv (recommended)
```bash
uv tool install nr-mcp
```
Or from source:
```bash
git clone https://github.com/Texan-NXTassist/nr-mcp.git
cd nr-mcp
uv tool install .
```
This creates the `nr-mcp` command in `~/.local/bin/`.
## Configuration
### Environment variables
| Variable | Required | Description |
|----------|----------|-------------|
| `NR_URL` | No | Node-RED URL (default: `http://localhost:1880`) |
| `NR_TOKEN` | No* | Bearer token for token-based auth |
| `NR_USER` | No* | Username for Basic Auth |
| `NR_PASS` | No* | Password for Basic Auth |
\* At least one auth method is recommended. Auth is checked in order: token → basic auth → no auth.
### Claude Desktop
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"nr-mcp": {
"command": "nr-mcp",
"env": {
"NR_URL": "http://localhost:1880",
"NR_USER": "admin",
"NR_PASS": "your-password"
}
}
}
}
```
> **Tip**: If you get a "working directory" error, create a wrapper script:
> ```bash
> #!/bin/bash
> cd /tmp
> exec nr-mcp "$@"
> ```
> Then point `command` to the wrapper path.
### Cursor / VS Code
Add to your MCP settings (`.cursor/mcp.json` or VS Code equivalent):
```json
{
"mcpServers": {
"nr-mcp": {
"command": "nr-mcp",
"env": {
"NR_URL": "http://localhost:1880",
"NR_TOKEN": "your-access-token"
}
}
}
}
```
## Usage examples
Once connected, you can ask your AI assistant things like:
- *"Show me all Node-RED tabs and their node counts"*
- *"Search for nodes that contain 'mqtt' in their code"*
- *"Show me the function code for node abc123"*
- *"Update the function code in node xyz to add error handling"*
- *"Create an inject node and an HTTP request node on the Weather tab"*
- *"What modules are installed? Is node-red-dashboard available?"*
- *"Install node-red-contrib-influxdb"*
- *"Trigger the 'Test' inject node and check for errors"*
## Architecture
nr-mcp is a Python MCP server that communicates with Node-RED via its [Admin API](https://nodered.org/docs/api/admin/). It uses `stdio` transport (standard for MCP) and makes HTTP calls to your Node-RED instance.
```
AI Assistant ↔ MCP (stdio) ↔ nr-mcp ↔ HTTP ↔ Node-RED Admin API
```
### Key design decisions
- **GET→POST pattern**: All deploys fetch full flows, modify in-place, then POST back. Never uses `PUT /flow/:id` which reorders tabs.
- **Optimistic locking**: Uses the Node-RED `rev` field to detect concurrent modifications.
- **No caching**: Every tool call fetches fresh data. Slightly slower, but always correct.
- **Single retry on conflict**: Deploy operations retry once on 409 Conflict.
For more details, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
## Node-RED setup
The Admin API must be enabled (it is by default). If you've restricted it, ensure these endpoints are accessible:
- `GET /flows` and `POST /flows` — flow read/write
- `GET /context/flow/:id` — flow context
- `POST /inject/:id` — inject trigger
- `GET /nodes` and `POST /nodes` — module management
See [Node-RED Admin API docs](https://nodered.org/docs/api/admin/) for auth configuration.
## Contributing
Contributions welcome! Please open an issue first to discuss what you'd like to change.
```bash
git clone https://github.com/Texan-NXTassist/nr-mcp.git
cd nr-mcp
uv venv && source .venv/bin/activate
uv pip install -e .
```
## License
MIT — see [LICENSE](LICENSE).