MrJ JMRI

Talk to your model railroad.

Bring AI to your JMRI powered layout. Connect your favorite AI assistant and control your DCC model railroad using natural language through voice or chat.

Drive locomotives, control turnouts, operate signals, manage layout accessories, and more — just by asking.

Compatible with MCP clients such as Claude Desktop, Claude Code, xiaozhi, and other MCP-compatible AI assistants.

Features

MrJ JMRI AI Assistant provides:

• Ready-to-use package for easy installation
• Full documentation with setup guides and usage examples
• A complete MCP (Model Context Protocol) server for JMRI integration
• A command-line interface (jmri-cli) for direct control, scripting, and automation
• 50 MCP tools exposing the main JMRI capabilities:
  • Power management
  • Locomotive throttles and functions
  • Roster management
  • Turnouts
  • Sensors
  • Layout lights
  • Signals
  • Blocks
  • Operating modes
  • Layout-wide meta tools (status overview, secure/night/day mode)

See the complete MCP tools reference in mcp-tools.md.

The goal is simple: make advanced JMRI control accessible to every model railroader, from casual operators to automation enthusiasts.

What can I say?

Pick the page that matches what you want to do — each links to the next. Available in English and French:

• 🚂 Conductor — just want to drive trains? Start here. English · Français
• 🔧 Tinkerer — managing power, turnouts, signals, and the whole layout. English · Français
• 🛠️ Engineer — full tool reference, CLI, scripting, and JMRI internals. English · Français

The conductor/tinkerer/engineer split is borrowed from DCC-EX, who came up with this framing first.

Installation

Getting started is designed to be simple.

See the installation guide and quick start guide for setup instructions, configuration, and first commands.

AI Assistant Setup

• Claude Desktop and Claude Code
• xiaozhi / Kira

Command Line Interface

The included CLI provides direct access to your JMRI layout without requiring an AI assistant.

It can be used for:

• Manual control
• Scripting
• Automation
• Testing and troubleshooting

See the CLI reference.

MCP Tools

The MCP server currently exposes 50 tools covering the main JMRI capabilities.

See the complete reference:

• MCP Tools Reference

Status

v1.0

The project is fully functional and actively maintained.

Future improvements, feature requests, and roadmap items are tracked in the project board and the issues.

Requirements

• Python ≥ 3.10 (developed on 3.12)
• A running JMRI Web Server (tested with JMRI 5.4)

See docs/install.md for installation details.

Documentation

Getting started

• Quick start — fastest path from a fresh installation to a working voice/chat command
• Installation — package installation, configuration, and verification

AI assistants

• Claude Desktop / Claude Code setup — connect your AI assistant to JMRI
• xiaozhi / Kira setup — expose JMRI control to voice assistants

Advanced users

• CLI reference — jmri-cli command reference
• Exhibition mode — restricted-safety mode for public demos
• Architecture — module design, JMRI clients, WebSocket implementation
• Testing — mocked and live test suites, hardware safety configuration
• Resources — references for JMRI, MCP, and xiaozhi/Kira

Project

• ACKNOWLEDGMENTS.md — thanks to the open-source projects this depends on
• CONTRIBUTING.md — contribution guidelines and project conventions

Configuration

Variable	Default	Description
JMRI_URL	http://localhost:12080	Base URL of the JMRI Web Server
EXHIBITION_PASSWORD	this is sparta	Password required to exit exhibition mode. See Exhibition mode.
EXHIBITION_ALLOWED_ADDRESSES	(none)	Comma-separated DCC addresses locomotives are restricted to while exhibition mode is on.
EXHIBITION_START_ON	(off)	If set to 1/true/yes/on, the server starts already in exhibition mode.

License

AGPL-3.0-or-later

Chosen deliberately over a permissive license (MIT/Apache) so that anyone who modifies this project and offers it as a network service (not just redistributes the code) must also publish their modified source.

See the license text for the exact terms.

Third-party code

xiaozhi_wrapper (part of the jmri-mcp package) is adapted from the MCP pipe example in xiaozhi-esp32 (MIT License, Copyright (c) 2025 Shenzhen Xinzhi Future Technology Co., Ltd. and Project Contributors).

See the package documentation:

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