# qucs-mcp

MCP server for [Qucs/QucsStudio](https://qucsstudio.de) 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.

```mermaid
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](https://qucsstudio.de) installed (download the zip, extract anywhere)
- Python 3.11+ (managed by [uv](https://docs.astral.sh/uv/))
- uv: `winget install astral-sh.uv` or `pip install uv`

## Setup

```powershell
# 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:

```json
{
  "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`](examples/voltage_divider.py).

<!-- TODO: add a short screen recording of an agent session designing and simulating a circuit -->

## Development

```powershell
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