nodered-mcp

Node-RED の flows.json を読み取り、照会し、編集する MCP サーバーです。

概要

Node-RED はすべてのフロー、ノード、ワイヤー、グループボックスを 1 つの大きな JSON ファイルに保存します。これを手作業で、あるいは jq や sed で編集すると、ぶら下がったワイヤー、自身のノードを覆わなくなったグループボックス、既存ノードの上に積み重なった新規ノードができてしまうものです。

このサーバーは、そのファイルを MCP クライアントに対して、フォーマットを理解した小さなツール群として公開します。フローノードと設定ノードの違いを認識し、ワイヤーパスを追跡でき、Node-RED エディタ自身のジオメトリを再現するため、描画するグループボックスはエディタが描画するものと一致します。

これは、ホームオートメーションリポジトリで Node-RED の変更をスクリプト化するために使用されていた flows_util.py / layout_util.py のペアを移植したもので、ファイルパス、コンテナ名、再起動コマンドをすべて設定可能に一般化しています。

Related MCP server: nr-mcp

機能

• 照会 — タブ、グループ、孤立ノード、サブフロー、参照されている Home Assistant エンティティ、フロー内のワイヤートレース。

• 編集 — ノードの作成、更新、削除、名前変更、複製、ワイヤーの接続・切断、グループの作成・追加・スタイル変更、ノードセットのインポート・エクスポート。

• 配置 — ノード作成前に空きキャンバスを確保して座標を推測せず、キャンバスの衝突を lint し、重なりを修復。

• 意図的なコミット — 編集はメモリ上に蓄積され、要求したときだけディスクに書き込まれるため、複数ノードの構築が 1 つの単位として反映されます。

• 2 つのガード — 元のスクリプトには不要だった保護機能: 新たな衝突を生む書き込みを拒否するレイアウトゲートと、ブラウザからデプロイされた flows.json を上書きしないようにする陳腐化チェック。

要件

• Python 3.11+

• ローカルファイルシステム上の flows.json

• PATH 上の Docker — deploy ツールのみで使用。ファイルをコンテナにコピーして再起動します。

インストール

git clone https://github.com/ljmerza/nodered-mcp
cd nodered-mcp
uv sync

使用方法

flows.json のパスのみが必須設定です。適切なデフォルト値がないため、サーバーはパスなしでは起動を拒否します。

uv run nodered-mcp --flows-path /path/to/nodered/data/flows.json

MCP クライアントへの登録

{
  "mcpServers": {
    "nodered": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/nodered-mcp", "nodered-mcp"],
      "env": {
        "NODERED_FLOWS_PATH": "/path/to/nodered/data/flows.json"
      }
    }
  }
}

より完全な例は .mcp.json.example を参照してください。

設定

すべての設定は CLI フラグ > 環境変数 > デフォルト値 の優先順位で解決されます。

Node-RED が通常の Docker 以外で管理されている場合は、--restart-cmd をその管理方法に向けてください:

NODERED_RESTART_CMD="docker compose restart {container}"

ツール

7 つのツールがあり、それぞれが op 引数でディスパッチします。

典型的な構築手順

nodered_query(op="tabs")                                   -> tab ids
nodered_layout(op="free_region", tab_id=TAB, w=800, h=200) -> {"x": 100, "y": 3240}
nodered_edit(op="create_node", tab_id=TAB, node_type="inject",
             name="tick", x=100, y=3240)                   -> node id
nodered_edit(op="create_node", tab_id=TAB, node_type="switch",
             name="gate", x=300, y=3240)                   -> node id
nodered_edit(op="wire", source_id=..., target_id=...)
nodered_group(op="create", name="My Flow", tab_id=TAB, node_ids=[...])
nodered_session(op="save")

上記の操作は、最後の save まで flows.json に一切触れません。

ファイル保護の仕組み

レイアウトゲート

save と deploy は編集の前後でキャンバスを lint し、編集によって新たなエラーレベルの検出項目が生じた場合は書き込みを拒否します:

ディスク上に既に存在する問題はブロックされません — ブロックされるのは編集によって生じたものだけです。ゲートが発動した場合の修正方法は通常次のいずれかです:

• nodered_layout(op="free_region") で空きキャンバスを確保し、そこに配置する

• nodered_group(op="refit", group_id=...) でグループをノードに合わせてリサイズする

• 意図的な重なりの場合は nodered_session(op="save", allow_overlap=true) を使用する

グループのジオメトリは正確です: サイズ計算ルールは Node-RED エディタから移植されているため、計算されたボックスはエディタが描画するものと一致します。ノードのジオメトリは、ラベルテキストの幅を除いて正確で、これは Helvetica メトリクスから近似されます — そのためノードレベルの検出項目は常に警告に留まります。

陳腐化チェック

Node-RED はブラウザで誰かが Deploy を押すたびに flows.json を書き換えます。セッションはファイルを読み込んだときの (mtime_ns, size) を記録し、書き込みのたびに再チェックします。ファイルが背後で変更されていた場合、その作業を黙って元に戻すのではなく、コミットが拒否されます。reload して編集をやり直すか、force=true を渡してください。

os.path.getmtime ではなくナノ秒を使用する理由: 浮動小数点のエポックは約マイクロ秒の精度しかないため、読み込みと同じティック内に書き込みが行われると等しいと比較され、チェックをすり抜けてしまいます。

スタンドアロン使用

両方のエンジンモジュールは、MCP とは独立してライブラリおよび CLI として動作します。

uv run python -m nodered_mcp.flows summary --flows-path /path/to/flows.json
uv run python -m nodered_mcp.layout --path /path/to/flows.json --fix boxes,move

from nodered_mcp.flows import Flows

f = Flows("/path/to/flows.json")
ox, oy = f.free_region(tab_id, w=1600, h=300)
f.create_node(tab_id, "inject", "tick", x=ox, y=oy)
f.save()

--fix boxes だけでは状況を悪化させます: リフィットにより一部のボックスが拡大し、隣接する非メンバーノードを飲み込むことがあります。boxes,move を一緒に実行し、--apply を渡す前にドライランを読んでください。

プロジェクト構成

src/nodered_mcp/
├── server.py       FastMCP server: the seven tools
├── session.py      in-memory session, stdout capture, staleness guard
├── config.py       CLI flags and environment resolution
├── flows.py        the Flows class, composed from the mixins below
├── constants.py    defaults, the group style, LayoutError
├── reports.py      ReadMixin      — summary, tab, group, search, trace
├── nodes.py        NodeEditMixin  — create/update/delete/wire nodes
├── groups.py       GroupMixin     — create and populate group boxes
├── placement.py    LayoutMixin    — claim free canvas, measure and refit boxes
├── transfer.py     TransferMixin  — import and export node sets
├── persist.py      PersistMixin   — save, deploy, and the layout gate
└── layout.py       canvas geometry and linter, ported from the NR editor

Flows がミックスインを合成するため、公開 API はフラットなままです: f.summary()、f.create_node()、f.free_region()、f.save()。

開発

uv sync --group dev
uv run pytest                    # 49 tests
uv run ruff check .
uv run ruff format --check .

テストは tests/fixtures/ の合成フィクスチャに対して実行され、実際の flows ファイルは使用しません。設定の優先順位、読み取りツール、保存までメモリ内に保持するセマンティクス、ブロックとオーバーライドの両方のレイアウトゲート、陳腐化ガード、デプロイコマンドシーケンス、そしてどのツールも stdout に書き込まないこと（余計な print は MCP の stdio フレーミングを壊します）をカバーしています。

CI は ljmerza/misc-actions を通じて同じチェックを実行します。

貢献

Issue とプルリクエストを歓迎します。ruff check、ruff format、pytest をグリーンに保ってください。

謝辞

• Node-RED — ここでのキャンバスジオメトリはエディタクライアントから移植されているため、グループボックスはエディタが描画するものと一致します。

• FastMCP — MCP サーバーフレームワーク。

ライセンス

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