# Nr Mcp

> MCP server for Node-RED — safe deploy, optimistic locking, smart search, 13 tools

- **Type:** MCP server
- **Install:** `agentstack add mcp-texan-nxtassist-nr-mcp`
- **Verified:** Pending review
- **Seller:** [Texan-NXTassist](https://agentstack.voostack.com/s/texan-nxtassist)
- **Installs:** 0
- **Latest version:** 1.2.2
- **License:** MIT
- **Upstream author:** [Texan-NXTassist](https://github.com/Texan-NXTassist)
- **Source:** https://github.com/Texan-NXTassist/nr-mcp

## Install

```sh
agentstack add mcp-texan-nxtassist-nr-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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).

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Texan-NXTassist](https://github.com/Texan-NXTassist)
- **Source:** [Texan-NXTassist/nr-mcp](https://github.com/Texan-NXTassist/nr-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Versions

- **1.2.2** — security scan: pending review — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-texan-nxtassist-nr-mcp
- Seller: https://agentstack.voostack.com/s/texan-nxtassist
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.