qucs-mcp

MCP server for Qucs/QucsStudio circuit simulation. Enables MCP-compatible agents to generate circuit schematics, run simulations, and parse results programmatically.

Why

LLM agents are getting good at reasoning about circuits, but they have no way to check their work: they can propose a divider network or a filter, yet cannot verify the numbers. This server closes that loop. It gives any MCP-compatible agent (Claude Desktop, Claude Code, or your own) a real SPICE-class simulator as a tool, so a design conversation becomes: propose a circuit, simulate it, read the actual operating point, and iterate until it is right.

Qucs/QucsStudio was chosen because its backend (qucssim.exe) runs fully headless, its schematic and netlist formats are plain text an agent can generate reliably, and it is free.

flowchart LR
    agent["MCP agent<br/>(Claude Desktop, Claude Code, ...)"] -->|create_schematic| sch[".sch + netlist"]
    sch -->|run_simulation| sim["qucssim.exe<br/>(headless)"]
    sim --> dat["binary .dat results"]
    dat -->|read_simulation_results| parsed["structured numeric data"]
    parsed --> agent

Related MCP server: ltspice-mcp

What it does

This MCP exposes tools that lets agents:

• Build a Qucs schematic from component descriptions

• Run the Qucs backend simulator (qucssim.exe) headlessly

• Parse the binary .dat result files into readable data

• Manage Qucs projects on disk

Prerequisites

• QucsStudio installed (download the zip, extract anywhere)

• Python 3.11+ (managed by uv)

• uv: winget install astral-sh.uv or pip install uv

Setup

# Clone the repo
git clone https://github.com/leonardoAB1/qucs-mcp.git
cd qucs-mcp

# Install dependencies
uv sync

# Set the path to your QucsStudio installation
$env:QUCS_HOME = "C:\Program Files\QucsStudio"

# Verify the server starts
uv run qucs-mcp

Claude integration

Add to %APPDATA%\Claude\claude_desktop_config.json or .claude/settings.json in your project:

{
  "mcpServers": {
    "qucs-mcp": {
      "command": "uv",
      "args": ["--directory", "C:\\path\\to\\qucs-mcp", "run", "qucs-mcp"],
      "env": {
        "QUCS_HOME": "C:\\Program Files\\QucsStudio"
      }
    }
  }
}

Environment variables

Available tools

Supported simulation types

Example: voltage divider via MCP

Ask an agent (with this MCP enabled):

Create a voltage divider with R1=10k and R2=10k, supply 5V, sweep the supply from 0 to 10V in 11 steps, run the DC simulation, and tell me the midpoint voltage at each step.

The agent will call create_schematic then run_simulation then read_simulation_results and report the values. The same flow, driven directly from Python instead of an agent, is in examples/voltage_divider.py.

Development

uv sync --extra dev
uv run pytest                          # unit tests
uv run pytest -k integration          # integration tests (requires QUCS_HOME)
uv run ruff check src/
uv run mypy src/
uv run mcp dev src/qucs_mcp/server.py  # open MCP Inspector in browser

License

MIT