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）
• 52 个 MCP 工具，提供 JMRI 主要功能：
  • 电源管理
  • 机车控制器和功能
  • 车辆名册管理
  • 道岔
  • 传感器
  • 布局照明
  • 信号
  • 区块
  • 运行模式
  • 整体布局元工具（状态概览、安全／夜间／日间模式）

请参阅 mcp-tools.md 中完整的 MCP 工具参考。

目标很简单：让每位模型铁路爱好者都能轻松使用 JMRI 的高级控制功能，无论是休闲操作者还是自动化爱好者。

基于真实硬件构建，而不只是依据 JMRI 文档

本项目针对一套使用多个控制站的真实 DCC++ 铁路布局开发，其中一些行为正是因为实际硬件的表现并不总是符合 JMRI API 文档的描述：

• 自动修复 UNKNOWN 电源状态。 重新发送控制站的当前电源状态（例如电源已经开启时，再执行一个简单的“设置电源为 ON”命令）是一个已知的 JMRI/DCC++ 陷阱：它会让系统进入 UNKNOWN 状态，而不是安全地不作处理。每条电源命令都会先重新读取当前状态，并跳过多余的 POST 请求；如果确实发出了 ON 请求，但结果仍为 UNKNOWN，系统会自动执行 OFF → 等待 → ON 的重试流程进行恢复，而不会让铁路布局陷入停滞。
• 每台机车各自绑定控制站。 在有多个 DCC 连接的铁路布局中，把机车的油门命令发送到错误的控制站不会报错——解码器只会悄无声息地收不到信号。Roster 条目可以通过 DccSystem 自定义属性声明其通常使用的连接（在 JMRI 的 Roster Entry → Edit → Attributes 选项卡中设置，例如将 DccSystem 设为 T），获取油门时会自动读取此属性，以便将命令发送到正确的控制站。
• 每个道岔、灯光和信号都会显示 DCC 连接和硬件地址。 列出道岔、灯光或信号时，会报告实际驱动它的 DCC 连接（根据其 JMRI 系统名称解析，例如 OT23 → ohara (turnouts)），并在 JMRI 能提供硬件地址的情况下一并显示原始硬件地址（道岔和灯光支持；目前 JMRI 的任何 API 都无法提供信号机的硬件地址，因此该字段会如实显示为未知，而不会进行猜测）。
• 每次写入后都会重新读取真实状态进行确认，而不是相信响应。 电源、道岔、灯光和信号命令执行后，都会重新读取 JMRI 的实际状态，并准确报告观察到的状态——包括状态与请求不一致的情况——而不是假定收到 200 响应就表示铁路布局已按要求执行。
• 即使由其他来源驱动，油门状态也会保持实时更新。 JMRI 会将每次油门更改（速度、方向、功能）广播给所有持有该机车的客户端，包括其他 JMRI 控制面板或第二个 MCP 会话。本项目的油门缓存会持续与此广播流同步，而不仅仅根据自身命令更新，因此即使其他人驾驶列车，也不会报告过时状态。

我可以怎么说？

选择与你想做的事情相符的页面——每个页面都会链接到下一步。提供英文和法文版本：

• 🚂 车长 — 只想驾驶列车？从这里开始。 English · Français
• 🔧 操作者 — 管理电源、道岔、信号和整个铁路布局。 English · Français
• 🛠️ 工程师 — 完整的工具参考、命令行、脚本和 JMRI 内部机制。 English · Français

车长／操作者／工程师这一分类借鉴自 DCC-EX，这种表述最初由他们提出。

安装

本项目旨在让入门过程简单易行。

关于所有安装组合（CLI、Claude Desktop .mcpb、Kira bridge）、配置和初始命令，请参阅安装指南。

更喜欢配有截图的分步教程？请参阅社区编写的 Instructable：通过与 Claude 聊天控制你的 JMRI 铁路。

AI 助手设置

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

命令行界面

jmri-cli 是一款功能齐全的布局命令行客户端，可直接与 JMRI 通信，无需 AI 助手或 MCP 客户端——MCP 工具能做的一切，人也都可以在终端中完成。

不带任何参数运行它即可打开交互式 Shell：建立一个持久连接，在命令之间持续保持机车运行、灯光点亮和控制权已获取（与一次性调用不同，后者会在退出时立即释放所有油门）。Shell 还提供了实用的命令行体验：使用上下方向键调出命令历史记录，并将记录保存在会话之间（~/.jmri-cli/shell_history）；支持整个命令树的 TAB 补全；支持以 ; 分隔的多命令行；提供 wait 命令，用于依次执行 --hold 和后续命令；此外，针对速度和方向，还支持更友好的类自然语言句式语法（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；若某条命令中明确指定了机车，则该命令会优先使用指定的机车。退出时始终会确保布局安全：任何仍在运行的机车都会触发减速并释放的提示；连接关闭前还会关闭正在运行的功能（灯光），而不会将其遗留在运行状态。

每条命令也都可以在普通终端中以一次性方式运行，用于脚本、自动化、快速手动检查或针对真实布局进行故障排查。

请参阅 CLI 参考。

MCP 工具

MCP 服务目前提供 52 个工具，涵盖 JMRI 的主要功能。

请参阅完整参考文档：

• MCP 工具参考

状态

v1.0

项目功能完整，并在积极维护中。

后续改进、功能请求和路线图条目均在项目看板和 issues 中跟踪。

要求

• 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）设置 — 在 OpenAI Codex 中注册 MCP 服务
• 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 构建并维护。

欢迎通过 issues 提出问题、报告错误和请求新功能。

许可证

AGPL-3.0-or-later

我们有意选择了此许可证，而非宽松许可证（MIT/Apache），因此任何修改本项目并将其作为网络服务提供（而不只是重新分发代码）的人，也必须公开其修改后的源代码。

具体条款请参阅许可证文本；重复使用本项目时所需的署名信息请参阅 NOTICE.md。

第三方代码

xiaozhi_wrapper（jmri-mcp 包的一部分）改编自 xiaozhi-esp32 中的 MCP pipe 示例（MIT License，Copyright (c) 2025 Shenzhen Xinzhi Future Technology Co., Ltd. and Project Contributors）。

请参阅包文档：

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