Qucs

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

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

Variable	Description	Default
QUCS_HOME	Root of the QucsStudio installation	Auto-discovered from common paths
QUCS_PROJECTS	Directory for Qucs projects	%HOMEPATH%\.qucs
QUCS_SIM_TIMEOUT	Simulation timeout in seconds	60

Available tools

Tool	Description
create_schematic	Generate a .sch file and netlist from component definitions
run_simulation	Run qucssim.exe on a netlist, return the .dat results path
read_simulation_results	Parse a .dat file into structured numeric data
create_project	Create a Qucs project directory under ~/.qucs
list_project_files	List all files in a project
list_components	Browse available component types from Qucs libraries

Supported simulation types

Type	Description
DC	DC operating point
AC	AC frequency sweep (gain, phase, impedance vs. frequency)
TR	Transient analysis (time-domain waveforms)
SW	Parameter sweep over a component value or source
SP	S-parameter analysis

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