nr-mcp

nr-mcp

AI アシスタントが Node-RED とやり取りできるようにする Model Context Protocol（MCP）サーバーです。フローの読み取り、ノードの検索、Function ノードのコード編集、安全な変更のデプロイ、モジュールの管理ができます。

実際の課題を解決するために開発されました。既存の Node-RED MCP 実装は PUT /flow/:id を使用するため、タブの順序が入れ替わります。nr-mcp は楽観的ロックを使った正しい GET → POST /flows パターンを使用するため、タブの順序が常に維持されます。

機能

Node-RED フローを完全に管理するための13 個のツール：

ツール	説明
nr_get_flow_summary	ノード数とグループを含む、すべてのタブの概要
nr_get_flow	名前または ID を指定して、すべてのノードを含む単一のタブを取得
nr_search_nodes	名前、種類、JavaScript コードの内容でノードを検索
nr_get_function_code	Function ノードから JS コード全体を抽出（初期化／終了処理を含む）
nr_get_node_config	上流／下流の接続情報を含む完全な設定
nr_get_flow_context	フローレベルのコンテキスト変数を読み取り
nr_safe_deploy	楽観的ロックを使って変更をデプロイ — タブの順序は決して変わりません
nr_create_nodes	1 回のデプロイでノード／グループを一括作成
nr_delete_nodes	配線とグループを自動的に整理して一括削除
nr_inject	フローのテスト用に、リモートから Inject ノードを実行
nr_get_installed_modules	インストール済みモジュールと利用可能なノードタイプを一覧表示
nr_install_module	Node-RED レジストリから npm パッケージをインストール
nr_get_debug_output	フローコンテキストからデバッグ／エラーデータを読み取り

既存の MCP サーバーを使わない理由

• タブ順序の変更バグ：ほかの実装は PUT /flow/:id を使用するため、Node-RED のタブ順序が気付かないうちに入れ替わります。nr-mcp は、正しい GET → POST /flows のフルデプロイパターンを使用します。
• 楽観的ロック：デプロイのたびに rev フィールドを確認します。読み取りから書き込みまでの間に別の人がデプロイした場合、データが気付かないうちに失われるのではなく、明確な競合エラーが返されます。
• スマート検索：1 回の呼び出しで、ノード名、種類、Function コード、テンプレート、アクションを横断して検索します。
• 本番環境での実績：複雑な Node-RED 環境（ホームオートメーション、IoT、エネルギー管理）の管理に日常的に構築・使用されています。

インストール

前提条件

• Python 3.11+
• uv（推奨）または pip
• Admin API が有効な Node-RED インスタンス

PyPI からインストール

pip install nr-mcp

uv でインストール（推奨）

uv tool install nr-mcp

またはソースから：

git clone https://github.com/Texan-NXTassist/nr-mcp.git
cd nr-mcp
uv tool install .

これにより、~/.local/bin/ に nr-mcp コマンドが作成されます。

設定

環境変数

変数	必須	説明
NR_URL	いいえ	Node-RED の URL（デフォルト：http://localhost:1880）
NR_TOKEN	いいえ*	トークンベース認証用の Bearer トークン
NR_USER	いいえ*	Basic Auth 用のユーザー名
NR_PASS	いいえ*	Basic Auth 用のパスワード

* 少なくとも 1 つの認証方式を設定することを推奨します。認証はトークン → Basic Auth → 認証なしの順に確認されます。

Claude Desktop

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "nr-mcp": {
      "command": "nr-mcp",
      "env": {
        "NR_URL": "http://localhost:1880",
        "NR_USER": "admin",
        "NR_PASS": "your-password"
      }
    }
  }
}

ヒント：「working directory」エラーが発生する場合は、ラッパースクリプトを作成してください。

#!/bin/bash
cd /tmp
exec nr-mcp "$@"

次に、command にラッパーのパスを指定します。

Cursor / VS Code

MCP 設定（.cursor/mcp.json または VS Code の同等の設定）に追加します。

{
  "mcpServers": {
    "nr-mcp": {
      "command": "nr-mcp",
      "env": {
        "NR_URL": "http://localhost:1880",
        "NR_TOKEN": "your-access-token"
      }
    }
  }
}

使用例

接続したら、AI アシスタントに次のようなことを尋ねられます。

• 「すべての Node-RED タブと、それぞれのノード数を表示して」
• 「コードに 'mqtt' を含むノードを検索して」
• 「ノード abc123 の Function コードを表示して」
• 「ノード xyz の Function コードを更新して、エラー処理を追加して」
• 「Weather タブに Inject ノードと HTTP リクエストノードを作成して」
• 「どのモジュールがインストールされている？ node-red-dashboard は利用できる？」
• 「node-red-contrib-influxdb をインストールして」
• 「'Test' Inject ノードを実行して、エラーがないか確認して」

アーキテクチャ

nr-mcp は、Admin API を介して Node-RED と通信する Python 製の MCP サーバーです。stdio トランスポート（MCP の標準）を使用し、Node-RED インスタンスに HTTP リクエストを送信します。

AI Assistant ↔ MCP (stdio) ↔ nr-mcp ↔ HTTP ↔ Node-RED Admin API

主な設計上の決定事項

• GET→POST パターン：デプロイのたびにフロー全体を取得し、その場で変更してから POST で書き戻します。タブの順序が変わる PUT /flow/:id は使用しません。
• 楽観的ロック：Node-RED の rev フィールドを使用して、同時変更を検出します。
• キャッシュなし：すべてのツール呼び出しで最新データを取得します。少し遅くなりますが、常に正確なデータを使用できます。
• 競合時の再試行は 1 回：デプロイ操作で 409 Conflict が発生した場合、1 回再試行します。

詳細については、docs/ARCHITECTURE.md を参照してください。

Node-RED のセットアップ

Admin API は有効にする必要があります（デフォルトで有効です）。アクセスを制限している場合は、次のエンドポイントにアクセスできることを確認してください。

• GET /flows および POST /flows — フローの読み取り／書き込み
• GET /context/flow/:id — フローコンテキスト
• POST /inject/:id — インジェクトトリガー
• GET /nodes および POST /nodes — モジュール管理

認証設定については、Node-RED Admin API docs を参照してください。

コントリビューション

コントリビューションを歓迎します。変更したい内容について、まず issue を作成してご相談ください。

git clone https://github.com/Texan-NXTassist/nr-mcp.git
cd nr-mcp
uv venv && source .venv/bin/activate
uv pip install -e .

ライセンス

MIT — LICENSE を参照してください。