# awr-mcp

An [MCP](https://modelcontextprotocol.io) server that lets AI assistants such as Claude
build, simulate and read circuits in **Cadence AWR Design Environment (Microwave Office)**.

Ask in plain language — *"match a 50 Ω port to a 100 Ω load at 3 GHz with a quarter-wave
line and plot |S11|"* — and the assistant places the elements, wires them, sets up the
sweep and equations, runs the simulation, adds graphs and markers, and reads the results
back.

![Demo: a quarter-wave transformer built from a prompt](docs/media/demo.gif)

> **Not affiliated with Cadence.** AWR, AWR Design Environment and Microwave Office are
> trademarks of Cadence Design Systems, Inc. This project only automates a licensed AWR
> installation through its public COM API; it does not include or distribute any AWR
> software.

## What it can do

| Area | Tools |
|---|---|
| Project | `awr_status`, `awr_new_project`, `awr_open_project`, `awr_save_project` (also *save as older version*) |
| Frequencies | `awr_set_frequencies` (linear / explicit), `awr_set_log_frequencies` |
| Schematics | `awr_add_schematic`, `awr_element_info`, `awr_add_element`, `awr_set_element_params`, `awr_remove_element`, `awr_connect`, `awr_add_wire`, `awr_describe_schematic` |
| Equations | `awr_add_equations` (stacked in evaluation order) |
| Graphs | `awr_add_graph` (rectangular, Smith, polar, tabular, …), `awr_add_measurement`, `awr_set_graph_axes` |
| Results | `awr_simulate`, `awr_get_data`, `awr_add_marker`, `awr_add_marker_at_extremum`, `awr_list_markers` |
| Annotation | `awr_add_graph_text`, `awr_add_schematic_text` |
| Escape hatch | `awr_run_python` — arbitrary Python against the AWR COM API |

The server also teaches the model the AWR quirks that otherwise produce silently wrong
results — unit scaling, equation evaluation order, sweep index syntax and more. They are
collected in [docs/AWR_SCRIPTING_NOTES.md](docs/AWR_SCRIPTING_NOTES.md).

## Requirements

- Windows with a licensed **AWR Design Environment** (tested with 25.1)
- Python 3.10+
- An MCP client, e.g. Claude Desktop or Claude Code

## Install

```bash
git clone https://github.com/efedemirerr/awr-mcp.git
cd awr-mcp
python -m venv .venv
.venv\Scripts\pip install .
```

### Claude Desktop

Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "AWR": {
      "command": "C:\\path\\to\\awr-mcp\\.venv\\Scripts\\awr-mcp.exe"
    }
  }
}
```

### Claude Code

```bash
claude mcp add awr -- C:\path\to\awr-mcp\.venv\Scripts\awr-mcp.exe
```

Then **start AWR first and close any start-up dialog** (such as "Check For Update") —
a modal dialog blocks the COM connection.

## Example prompts

- *"Build a quarter-wave transformer that matches a 50 Ω port to a 100 Ω load at 3 GHz,
  sweep 1–5 GHz and plot |S11| in dB with a marker at 3 GHz."*
- *"Model a 2.2 nF capacitor with 0.5 cm AWG-30 copper leads, including skin-effect
  resistance and lead inductance, and plot |Z| from 10 MHz to 10 GHz on log axes with a
  marker at the self-resonance."*
- *"Plot the voltage standing-wave pattern along a 12 cm line terminated in 150 Ω."*
- *"Open my project, list the schematics and tell me the S21 at 2.4 GHz."*

[examples/quarter_wave_transformer.py](examples/quarter_wave_transformer.py) runs the
first example directly, without an assistant:

```bash
.venv\Scripts\python examples\quarter_wave_transformer.py
```

## How it works

The server attaches to the running AWR instance via `win32com` (ProgID `AWR.MWOffice`).
COM objects are apartment-bound, so every call runs on one dedicated single-threaded
apartment worker. Tool results are plain JSON, so the assistant can check its own work —
for example, `awr_describe_schematic` reports every parameter in SI units.

## Limitations

- Windows only, and AWR must already be running.
- Tested with AWR Design Environment 25.1 on Windows 11; other versions may differ.
- Focused on circuit schematics and linear simulation. Layout, EM and system (VSS)
  documents are reachable only through `awr_run_python`.
- `awr_run_python` executes arbitrary code with your user's privileges. Only connect this
  server to assistants and prompts you trust.

## Contributing

Issues and pull requests are welcome — especially reports from other AWR versions and new
entries for the scripting notes.

## License

MIT — see [LICENSE](LICENSE).

---

### Türkçe özet

**awr-mcp**, Claude gibi yapay zekâ asistanlarının Cadence AWR Design Environment'ta
(Microwave Office) devre kurmasını, simüle etmesini ve sonuçları okumasını sağlayan bir
MCP sunucusudur. AWR'yi açık bir COM arayüzü üzerinden kontrol eder; lisanslı bir AWR
kurulumu gerekir ve Cadence ile bağlantısı yoktur. Kurulum ve kullanım adımları
yukarıdadır; AWR otomasyonunda karşılaşılan tuzaklar
[docs/AWR_SCRIPTING_NOTES.md](docs/AWR_SCRIPTING_NOTES.md) dosyasında toplanmıştır.