JMRI MCP

MrJ JMRI AI アシスタント

フランス語版

ライセンスとクレジット表記 — この作品を再利用する前にお読みください。 このプロジェクトは HO44 PROJECT (MrJ) が著作権を有し、AGPL-3.0-or-later の下でライセンスされています（LICENSE を参照）。 このプロジェクトの一部（jmri-core、jmri-cli、jmri-mcp、.mcpb／.codex.zip バンドル、ドキュメント）を再配布、改変、再公開する場合は、このリポジトリ上でも、それ以外の場所でも（フォーク、別のプラットフォーム、パッケージレジストリ、動画、記事など）、必ず次の条件を守ってください。

• 元の著作者クレジット（MrJ / HO44 PROJECT）と、このリポジトリへのリンクを残すこと。
• 再配布版または改変版にも、同じ AGPL-3.0-or-later ライセンスを適用すること。

このクレジット表記を削除したり隠したりすることは、単なるマナー違反ではありません。AGPL-3.0 に基づくライセンス違反であり、違反として扱われます。詳細は NOTICE.md をご覧ください。

質問や一般的な議論には、GitHub Discussionsをご利用ください。 バグ報告や機能リクエストには、Issuesをご利用ください。

鉄道模型をモデルに話しかけて操作しましょう。

JMRI を活用したレイアウトに AI を導入しましょう。お好みの AI アシスタントを接続して、音声やチャットで自然言語を使い、DCC 鉄道模型を操作できます。

機関車の運転、分岐器の制御、信号機の操作、レイアウトアクセサリーの管理などを、話しかけるだけで行えます。

Claude Desktop、Claude Code、xiaozhiなどの MCP クライアントや、その他の MCP 対応 AI アシスタントと互換性があります。

機能

MrJ JMRI AI アシスタントの機能：

• 簡単にインストールできる、すぐに使えるパッケージ
• セットアップガイドと使用例を含む、充実したドキュメント
• JMRI と連携する完全な MCP（Model Context Protocol）サーバー
• 直接操作、スクリプト作成、自動化に使えるコマンドラインインターフェイス（jmri-cli）
• JMRI の主な機能を利用できる 52 個の MCP ツール：
  • 電源管理
  • 機関車のスロットルと機能
  • 車両名簿の管理
  • 分岐器
  • センサー
  • レイアウト照明
  • 信号機
  • ブロック
  • 運転モード
  • レイアウト全体のメタツール（ステータス概要、セキュア／夜間／昼間モード）

MCP ツールリファレンスで、MCP ツールの全一覧をご覧ください。

目標はシンプルです。気軽に運転を楽しむ人から自動化愛好家まで、すべての鉄道模型愛好家が高度な JMRI 制御を利用できるようにすることです。

JMRI のドキュメントだけでなく、実機を使って開発

このプロジェクトは、複数のコマンドステーションを備えた実際の DCC++ レイアウトで開発されました。実機の挙動が JMRI API のドキュメントから想定されるとおりとは限らないため、固有の動作がいくつか実装されています。

• UNKNOWN の電源状態を自動修復します。 コマンドステーションの現在の電源状態を再送する（すでに ON のときに単純に「電源を ON に設定」する）ことは、既知の JMRI／DCC++ の落とし穴です。安全な何もしない操作になるどころか、システムが UNKNOWN 状態に陥ります。すべての電源コマンドで、まず現在の状態を読み直し、冗長な POST を省略します。それでも正当な ON リクエストの結果が UNKNOWN になった場合は、レイアウトを動かないままにせず、OFF → 待機 → ON の再試行シーケンスで自動的に復旧します。
• 機関車ごとにコマンドステーションとの紐付けを設定できます。 DCC 接続が複数あるレイアウトで、機関車のスロットルコマンドを誤ったコマンドステーションに送っても、エラーにはなりません。デコーダーに届かず、何も聞こえないだけです。ロスターエントリーには、DccSystem カスタム属性を使って通常使用する接続を指定できます（JMRI の「Roster Entry」→「Edit」→「Attributes」タブで設定します。例：DccSystem = T）。スロットルの取得時にこの属性を自動的に読み取り、正しいステーションを指定します。
• すべての分岐器、ライト、信号に DCC 接続とハードウェアアドレスを表示します。 分岐器、ライト、信号の一覧には、実際に制御する DCC 接続を JMRI のシステム名（例：OT23 → ohara (turnouts)）から特定して表示します。また、JMRI が公開している場合はハードウェアアドレスも併せて表示します（分岐器とライトが対象です。信号マストは現在、どの JMRI API からもアドレスを取得できないため、推測せず「不明」と正直に表示します）。
• 書き込み後は必ず実際の状態を読み直して確認し、応答を鵜呑みにしません。 電源、分岐器、ライト、信号の各コマンドは、操作後に JMIR の実際の状態を読み直し、観測された内容を正確に報告します。要求した内容と異なる場合もそのまま報告し、200 応答が返っただけでレイアウトが要求どおりに動作したとは見なしません。
• 別の場所から操作しても、スロットルの状態を常に最新に保ちます。 JMRI は、速度、方向、機能など、スロットルの変更をその機関車を保持しているすべてのクライアントにブロードキャストします。ほかの JMRI パネルや、2 つ目の MCP セッションも対象です。このプロジェクトのスロットルキャッシュは、自身のコマンドだけでなく、そのストリームとも継続的に同期するため、ほかの人が列車を操作した後に古い状態を報告することはありません。

どのページを見ればよいですか？

やりたいことに合ったページを選んでください。各ページから次のページへ進めます。英語とフランス語で利用できます。

• 🚂 運転士 — 列車を運転したい方はこちらから。 英語 · フランス語
• 🔧 愛好家 — 電源、分岐器、信号、レイアウト全体を管理する方はこちら。 英語 · フランス語
• 🛠️ エンジニア — ツールの完全なリファレンス、CLI、スクリプト、JMRI の内部仕様はこちら。 英語 · フランス語

運転士／愛好家／エンジニアという区分は、最初にこの枠組みを考案した DCC-EX から借用しています。

インストール

すぐに使い始められるよう、シンプルに設計されています。

あらゆるインストール方法（CLI、Claude Desktop .mcpb、Kira ブリッジ）、設定、最初に実行するコマンドについては、インストールガイドをご覧ください。

スクリーンショット付きの手順を追ったガイドをご希望ですか？ コミュニティの Instructable「Claude とのチャットで JMRI の鉄道を制御する」をご覧ください。

AI アシスタントのセットアップ

• Claude Desktop と Claude Code
• Codex（ChatGPT）
• xiaozhi / Kira

コマンドラインインターフェース

jmri-cli はレイアウト用の高機能なコマンドラインクライアントです。AI アシスタントや MCP クライアントを必要とせず、JMRI と直接通信します。MCP ツールで実行できることはすべて、ターミナルから人が操作できます。

引数を指定せずに実行すると、インタラクティブシェルが起動します。これは、コマンド間も接続を維持する単一の永続的な接続で、機関車の走行、点灯、選択状態が保たれます（1 回限りの実行では、終了した瞬間にすべてのスロットルが解放されます）。シェルには、便利なコマンドライン機能も備わっています。セッションをまたいで保存される上下矢印キーによるコマンド履歴（~/.jmri-cli/shell_history）、コマンドツリー全体を対象にしたTAB 補完、; 区切りの複数コマンド行、--hold と後続のコマンドを順番に実行する wait コマンド、速度や方向を指定する、より使いやすい自然言語風の文形式構文（speed Autorail at 30 for 30 up 5 down 6 forward、または move Autorail forward at 30 for 30）があり、通常のフラグ形式も使用できます。select <loco> でセッション中に使用する機関車を選択すると、プロンプトがその名前に切り替わり、それ以降は、機関車の引数が省略可能または必須の各コマンド（stop、speed 40、function-on F0、...）が、clear を実行するまで自動的にその機関車を対象にします。コマンド行で機関車を明示的に指定した場合は、そのコマンドに限り選択状態が上書きされます。終了時には、常にレイアウトの安全が確保されます。走行中の機関車がある場合は、減速してから解放するためのプロンプトが表示され、接続を閉じる前に有効な機能（ライト）がオフになります。機能を有効にしたまま放置されることはありません。

すべてのコマンドは、スクリプト作成、自動化、実際のレイアウトに対する簡単な手動確認やトラブルシューティングのため、通常のターミナルから 1 回限りで実行することもできます。

CLI リファレンスを参照してください。

MCP ツール

MCP サーバーは現在、JMRI の主な機能を網羅する 52 個のツールを公開しています。

完全なリファレンスはこちらを参照してください。

• MCP ツールリファレンス

ステータス

v1.0

プロジェクトは完全に動作し、積極的にメンテナンスされています。

今後の改善、機能のリクエスト、ロードマップの項目は、プロジェクトボードとイシューで管理されています。

要件

• Python ≥ 3.10（3.12 で開発）
• 稼働中の JMRI Web Server（JMRI 5.4 でテスト済み）

インストールの詳細については、docs/install.mdを参照してください。

ドキュメント

はじめに

• インストールガイド — あらゆるインストール構成（CLI、Claude Desktop .mcpb、Kira ブリッジ）、設定、最初のコマンド
• このリポジトリでの開発 — コード自体の作業に使う、クローンしたコピーからの編集可能なインストール

AI アシスタント

• Claude Desktop / Claude Code のセットアップ — AI アシスタントを JMRI に接続
• Codex (ChatGPT) のセットアップ — MCP サーバーを OpenAI Codex に登録
• xiaozhi / Kira のセットアップ — 音声アシスタントから JMRI を操作できるようにする

上級ユーザー向け

• CLI リファレンス — jmri-cli のコマンドリファレンス
• 展示モード — 公開デモ用の安全制限モード
• アーキテクチャ — モジュール設計、JMRI クライアント、WebSocket の実装
• テスト — モックテストおよび実環境テストのスイート、ハードウェアの安全設定
• リソース — JMRI、MCP、xiaozhi/Kira の参考情報

プロジェクト

• ACKNOWLEDGMENTS.md — 依存しているオープンソースプロジェクトへの謝辞
• CONTRIBUTING.md — 貢献ガイドラインとプロジェクトの規約

設定

変数	デフォルト	説明
JMRI_URL	http://localhost:12080	JMRI Web Server のベース URL
EXHIBITION_PASSWORD	this is sparta	展示モードを終了するために必要なパスワード。展示モードを参照してください。
EXHIBITION_ALLOWED_ADDRESSES	(なし)	展示モードがオンの間、機関車に使用を制限する DCC アドレスをカンマ区切りで指定します。
EXHIBITION_START_ON	(オフ)	1／true／yes／on に設定すると、サーバーは最初から展示モードで起動します。

クレジット

MrJ が開発およびメンテナンスを行っています。

質問、バグ報告、機能リクエストは、イシューからお寄せください。

ライセンス

AGPL-3.0-or-later

MIT／Apache のような寛容なライセンスではなく、このライセンスを意図的に選択しました。これにより、このプロジェクトを改変してネットワークサービスとして提供する人は（コードを再配布するだけの場合に限らず）、改変したソースも公開する必要があります。

正確な条件についてはライセンス本文を、再利用時に必要な帰属表示についてはNOTICE.mdを参照してください。

サードパーティのコード

xiaozhi_wrapper（jmri-mcp パッケージの一部）は、xiaozhi-esp32 の MCP パイプの例を元にしています（MIT License、Copyright (c) 2025 Shenzhen Xinzhi Future Technology Co., Ltd. and Project Contributors）。

パッケージのドキュメントを参照してください。

packages/jmri-mcp/src/xiaozhi_wrapper/__init__.py