Logisim Live MCP

Let AI agents design digital circuits in Logisim Evolution, live.

Logisim Live MCP is a Model Context Protocol server that lets Claude, Codex, ChatGPT or any MCP client build, wire, inspect and simulate circuits in Logisim Evolution. Every edit appears immediately in the running Logisim window as a normal, undoable action, the way the Blender MCP drives Blender. The agent understands the circuit through data that comes from Logisim itself (exact ports, the real netlist, simulated values), not through screenshots.

What it looks like

Ask "build a full adder with inputs A, B, Cin and outputs S, Cout, then prove it works". The agent places the parts, wires them by port name (A to X1.in1, X1.out to N2.in1, ...) while you watch them appear in Logisim, and then checks its work:

> view_circuit("main")
    50        150       250       350       450       550       650
    ┬    ·    ┬    ·    ┬    ·    ┬    ·    ┬    ·    ┬    ·    ┬    ·
       ╔═╗
       ║AO────────┐╔═════╗
       ╚═╝        ├I     ║
130         XOR X1│║XOR XO────────┐
                 ┌┘║     ║        │
                 │┌I     ║        │╔═════╗
                 ││╚═════╝        ├I     ║
       ╔═╗       ││         XOR X2│║XOR XO───────────────────────IS║
       ║BO──────┬┼┘               │║     ║
       ...

> diagnose_circuit("main")
main: 10 components, 8 nets, no problems

> simulate_circuit("main", all_combinations=true)
A  B  Cin  |  S  Cout
0  0    0  |  0     0
0  0    1  |  1     0
...
1  1    1  |  1     1

Related MCP server: Rayzia MCP

Features

• Live, undoable editing. Opening or creating a project shows it in Logisim (launching it if needed). Each tool call becomes one Logisim action: it repaints at once, can be undone with Ctrl+Z, and is validated by Logisim, so an unknown component, a bad property value or an invalid circuit name is rejected and nothing changes.

• Understanding without screenshots. describe_component gives a part's exact ports (names, TTL pin numbers, direction, bit width, offsets) and properties (types, options, defaults). inspect_circuit gives the netlist exactly as Logisim connects it, with live values. view_circuit draws the layout as text. diagnose_circuit finds unconnected ports, floating or conflicting nets, width mismatches, dangling wires and overlaps.

• Wiring by name that cannot short nets. connect_ports("U1.pin13", "G2.in1") routes an orthogonal wire around real device and label boxes. Logisim joins wires at any wire end or port that touches them, so the router never runs along, bends on, or touches another net; it taps existing wires of the same net like a person would.

• Proof by simulation. simulate_circuit returns truth tables, explicit rows or clocked sequences from Logisim's own simulator in a private state, plus internal nets you watch. Headless --test-vector runs are supported too.

• Works with you, not around you. Your own edits in the window (and Ctrl+Z) are pulled back before the agent's next step. Saves are validated, backed up and atomic, and the window is marked as saved without reloading.

• Hierarchical designs. Several circuits per file, subcircuits addressed by their pin labels, main-circuit selection. Verified on a 4-bit ripple adder built from full-adder subcircuits (512/512 simulated rows correct).

• No startup dialogs. Stale Logisim autosaves, which normally trigger "save autosave" prompts and file choosers, are archived instead of blocking the window.

• Safe by design. Access is limited to one project folder; no arbitrary file or XML write tool; the in-Logisim plugin listens on loopback only with a per-user token.

Quick start

Requirements: Python 3.11+, Java 21+ (for Logisim Evolution 5.0.0), and an MCP client.

Windows (PowerShell, in the cloned repository):

Set-ExecutionPolicy -Scope Process Bypass
.\scripts\install-windows.ps1 -ProjectRoot "$env:USERPROFILE\Documents\LogisimProjects"

Linux / macOS:

scripts/install.sh ~/LogisimProjects

The installer creates .venv, installs the server, downloads the official Logisim Evolution 5.0.0 JAR and verifies its SHA-256, runs a health check, and writes ready-to-paste client configs to generated-config/. Then connect your client:

Details: docs/clients.md and docs/install-windows.md.

Example prompts

• "Create alu.circ and build a 1-bit ALU with AND, OR and ADD selected by a 2-bit op code. Check it with diagnose_circuit and a full truth table."

• "Open lab3.circ, explain what circuit main does from its netlist, and find wiring mistakes."

• "Use one 7421 chip to implement two 2-input AND gates (a 7408 half), tie the unused inputs high, and prove it with simulate_circuit."

• "Add a 4-bit register clocked by CLK to counter.circ and show its outputs over 8 clock cycles."

Tools

38 tools in five groups (full reference: docs/tools.md):

How it works

MCP client --stdio--> Python bridge --loopback TCP + token--> live plugin inside Logisim
                      XML model (saved file)                  applies edits as Logisim actions,
                      diff per tool call                      reports ports, nets, values,
                      port-aware router                       simulates in private states

The bridge keeps an XML model of the project (what gets saved) and diffs it before and after each tool call. The difference goes to a small Java plugin that Logisim loads through the standard -javaagent switch; it applies the change through Logisim's own model APIs, so the result is exactly what a user editing by hand would get. A revision counter detects hand edits, and saves are verified against the window. More in docs/architecture.md, docs/live-editing.md and docs/understanding.md.

Documentation

Example circuits built by the agent are in examples/circuits.

Status and limitations

• Built and tested for Logisim Evolution 5.0.0 on Windows and Linux (real GUI tests under Xvfb). macOS should work but is not yet tested.

• One project is open per server session. Logisim windows started by hand have no plugin; close them once and the bridge relaunches Logisim.

• VHDL components and FPGA board mapping are not covered by dedicated tools.

License

• Python bridge (src/, scripts/, tests/, docs): MIT.

• Live plugin (java-plugin/, and the built logisim-mcp-live-plugin.jar): runs inside Logisim Evolution and uses its APIs, so it is licensed GPL-3.0-or-later, like Logisim Evolution.

Logisim Evolution is developed by the Logisim Evolution team and is not affiliated with this project.