bltspice_mcp

Create any LTSpice circuit using LLMs!

Converts ltspice netlist .net to ltspice .asc file format!

REALTIME LTSpice simulation and export to .csv!

Project Layout

• src/bltspice_mcp/ server source code
• tests/unit/ unit tests
• tests/integration/ integration tests
• testfiles/ copied example assets (.asc/.log/.raw/.asy/.txt/.net/.kicad_sch)
• examples/codex/ and examples/opencode/ MCP call recipes for LLM agents
• config.json server configuration
• bltspice_mcp_for_LLM.md LLM tool-calling reference

Requirements

• Python 3.11+
• LTspice installed
• Linux/macOS with Wine for Windows LTspice binary

Quick Setup

python3 -m venv .venv
. .venv/bin/activate
pip install -U pip
pip install "PyLTSpice>=6.0.1" "fastmcp==2.14.7" "electronics-design>=0.2.3" pytest pytest-asyncio
pip install -e .

Configuration

config.json (absolute paths required):

{
  "mcp_server_name": "My PyLTSpice MCP Server",
  "mcp_server_url": "http://localhost:7543",
  "wine_path": "/usr/bin/wine",
  "ltspice_path": "/home/brosnan/.wine/drive_c/Program Files/ADI/LTspice/LTspice.exe",
  "enable_extra_tools": true,
  "timeout": 600,
  "convert_settings": {
    "ltspice_windows_path": "C:\\users\\brosnan\\AppData\\Local\\LTspice\\",
    "ltspice_wine_path": "~/.wine/drive_c/users/brosnan/AppData/Local/LTspice/",
    "custom_search_paths": ["./valid_asy/"],
    "minimum_dist": 32,
    "wire_pin_out_dist": 16,
    "grid_size": 16,
    "autoplace_iter": 12,
    "ltspice_version": 4.1,
    "voltage_must_have_dc": true,
    "kicad_path": "/usr/share/kicad/"
  }
}

convert_settings is optional. Each setting is optional and receives a default when omitted. Relative custom_search_paths are resolved from the server project root; Windows paths remain in Windows syntax for Wine-based conversion.

mcp_server_url supports http://, https://, and stdio://.

Run Server

Stdio transport:

. .venv/bin/activate
python -m bltspice_mcp --config /home/brosnan/bltspice_mcp/bltspice_mcp/config.json

MCP Client Config Examples

OpenCode

{
  "mcpServers": {
    "bltspice_mcp": {
      "command": "/home/brosnan/bltspice_mcp/bltspice_mcp/.venv/bin/python",
      "args": [
        "-m",
        "bltspice_mcp",
        "--config",
        "/home/brosnan/bltspice_mcp/bltspice_mcp/config.json"
      ]
    }
  }
}

Claude Code

{
  "mcpServers": {
    "bltspice_mcp": {
      "command": "/home/brosnan/bltspice_mcp/bltspice_mcp/.venv/bin/python",
      "args": [
        "-m",
        "bltspice_mcp",
        "--config",
        "/home/brosnan/bltspice_mcp/bltspice_mcp/config.json"
      ]
    }
  }
}

OpenAI Codex

{
  "mcp_servers": {
    "bltspice_mcp": {
      "command": "/home/brosnan/bltspice_mcp/bltspice_mcp/.venv/bin/python",
      "args": [
        "-m",
        "bltspice_mcp",
        "--config",
        "/home/brosnan/bltspice_mcp/bltspice_mcp/config.json"
      ]
    }
  }
}

Response Contract

Server statuses:

• performing LTspice operation in progress
• LTspice operation completed!
• invalid input!
• file not found!
• unsupported file type!
• simulator not configured!
• simulation failed!
• parser failed!
• LTspice operation timed out!
• internal error

Each payload includes operation. Successful responses include output, and optionally output_obj_name.

Session-isolated stop_reset

Each MCP session owns a dedicated OS worker process group containing its dispatcher registry, PyLTSpice RunTask threads, simulator subprocesses, and callback children. stop_reset interrupts that session immediately with SIGKILL, clears operations that were already queued for it, and discards its object registry. It does not signal worker groups belonging to other MCP sessions. Because operating systems apply SIGKILL to processes rather than individual threads, killing the session worker process terminates all of its threads atomically.

The immediate response is the normal in-progress payload. Poll execute_status until both status is complete and operation is stop_reset. Its output includes worker_process_killed, processes_killed, threads_terminated_with_processes, and queued_operations_killed. Work submitted after the reset call waits until the reset completes and runs in a fresh session worker.

traces_to_csv via execute

Convert selected traces from a loaded RawRead object into one CSV per wave/step.

Inputs:

• object_name: name of a stored RawRead object
• trace_refs: array of trace names (any length), for example ["V(opamp_input)", "V(opamp_output)"]
• output_files:
  • string prefix/path, example ./sim_wave_ -> writes ./sim_wave_0.csv, ./sim_wave_1.csv, ...
  • or array of explicit .csv paths with one entry per wave

Example MCP call:

{"tool":"execute","arguments":{"api_name":"traces_to_csv","inputs":{"object_name":"raw","trace_refs":["V(opamp_input)","V(opamp_output)"],"output_files":"./sim_wave_"}}}

LTspice schematic conversion via execute

The following electronics-design APIs are available through execute: is_valid_ltspice_netlist_file, ltspice_netlist_to_asc, kicad_sch_to_ltspice_netlist, and ltspice_netlist_to_kicad_sch.

The conversion APIs receive the configured convert_settings automatically. A request may include an inputs.convert_settings object to override individual values for that call. is_valid_ltspice_netlist_file only requires its filepath. voltage_must_have_dc must be a JSON boolean and is passed to ltspice_netlist_to_asc inside convert_settings.

KiCad conversions require kicad_path to point at a directory containing KiCad symbol libraries (default /usr/share/kicad/). It can be set in config.json or overridden per request inside inputs.convert_settings. Other electronics-design KiCad generation settings keep their package defaults.

Example MCP calls:

{"tool":"execute","arguments":{"api_name":"kicad_sch_to_ltspice_netlist","inputs":{"kicad_sch_filepath":"/abs/path/input.kicad_sch","ltspice_netlist_filepath_out":"/abs/path/output.net"}}}

{"tool":"execute","arguments":{"api_name":"ltspice_netlist_to_kicad_sch","inputs":{"ltspice_netlist_filepath":"/abs/path/input.net","kicad_sch_filepath_out":"/abs/path/output.kicad_sch"}}}

kicad_sch_to_ltspice_netlist converts one KiCad schematic into one validated LTspice netlist. ltspice_netlist_to_kicad_sch converts one validated LTspice netlist into one validated KiCad schematic. Both return the electronics-design conversion tuple [true, "OK", 0] on success or [false, "<error code>", <line>] on failure inside output.result.

run_ltspice_to_csv.py Equivalent MCP Flow

Equivalent artifacts are included for the op-amp example workflow:

• netlist fixture: /home/brosnan/bltspice_mcp/bltspice_mcp/testfiles/opampdouble.net
• Codex recipe: /home/brosnan/bltspice_mcp/bltspice_mcp/examples/codex/run_ltspice_to_csv.md
• OpenCode recipe: /home/brosnan/bltspice_mcp/bltspice_mcp/examples/opencode/run_ltspice_to_csv.md
• integration test: /home/brosnan/bltspice_mcp/bltspice_mcp/tests/integration/test_run_ltspice_to_csv_via_mcp.py

Integration Coverage

Integration tests now include:

• Core MCP flow test (runtime_info, execute, execute_status, stop_reset)
• Mapping coverage for the checked-in PyLTSpice example-name manifest (tests/fixtures/pyltspice_example_manifest.json)
• Mapping coverage for the checked-in README example-name list in that manifest
• End-to-end run_ltspice_to_csv.py style MCP workflow for opampdouble.net
• KiCad conversion MCP workflows for kicad_sch_to_ltspice_netlist and ltspice_netlist_to_kicad_sch (tests/integration/test_kicad_conversion_via_mcp.py)

Run Tests (One By One)

. .venv/bin/activate
pytest -q tests/unit/test_responses.py
pytest -q tests/unit/test_config.py
pytest -q tests/unit/test_dispatcher.py
pytest -q tests/unit/test_session.py
pytest -q tests/integration/test_mcp_server_integration.py
pytest -q tests/integration/test_examples_via_mcp.py
pytest -q tests/integration/test_readme_examples_via_mcp.py
pytest -q tests/integration/test_run_ltspice_to_csv_via_mcp.py
pytest -q tests/integration/test_kicad_conversion_via_mcp.py

Notes

• runtime_info is immediate and does not require execute_status polling.
• Server queues execute in FIFO per MCP session; stop_reset interrupts only that session's worker process group and clears its existing queue.
• execute_status polls the latest status for queued operations.
• Completion/error notifications are emitted through MCP notification channel.