gowin-mcp

Beta. Working and in daily use, but verified against a narrow slice of Gowin output so far — see Beta status before trusting a number that matters. Bug reports with a sample report attached are very welcome.

An MCP server that turns Gowin EDA build reports into structured data.

Gowin EDA writes everything you need after a place & route — resource usage, achieved frequency per clock, the exact register-to-register path that failed setup — and then buries it in a multi-megabyte HTML file nobody opens. This server reads those artifacts and hands back the numbers.

Built for Sipeed Tang boards (GW1N / GW2A / GW5A) but it only cares about the report format, so any Gowin EDA project works.

What it answers

• Did this build close timing, and if not, which path failed and by how much?

• What is the achieved fMax on each clock domain versus its constraint?

• How much of the device am I using — CLS, LUT, ALU, registers, BSRAM, DSP, I/O?

• What did my last change cost me? (gowin_compare diffs two builds.)

Related MCP server: forgejo-mcp

Install

git clone https://github.com/Papipapito/gowin-mcp.git
cd gowin-mcp
npm install
npm run build

Then register it. For Claude Desktop, in claude_desktop_config.json:

{
  "mcpServers": {
    "gowin": {
      "command": "node",
      "args": ["C:\\path\\to\\gowin-mcp\\dist\\index.js"]
    }
  }
}

For Claude Code:

claude mcp add gowin -- node /path/to/gowin-mcp/dist/index.js

Tools

Every tool takes format: "json" if you want the raw structures instead of text.

Paths are forgiving: pass the project directory, its impl/ directory, or the .rpt.txt itself.

Example

Build: project  (GW5AT-60, GW5AT-LV60PG484AC1/I0)
Tool:  V1.9.11.03 Education
Built: Thu Jul 16 20:58:03 2026   PnR 0h 3m 29s   peak 1848MB

Resources
  Logic: 28034/59904 (47%)
    LUT 21883, ALU 3325, ROM16 0
  CLS: 19618/29952 (66%)
  Register: 15014/60780 (25%)
  BSRAM: 73/118 (62%)
  DSP: 10.5/118 (9%)
  I/O Port: 141/297 (48%)

Timing: 3 VIOLATIONS
  setup clk_54m    -1.826 ns  1 endpoint failing setup — worst path -1.826 ns:
                              cpu1/u0/ISet_1_s87/Q -> mem1/ram_busy_s0/CE
  setup clk_hdmi   -0.378 ns  ...
  hold  clk_27m    -0.028 ns  ...

fMax per clock
  clk_54m: 33.548 MHz vs 53.996 MHz constraint (-20.448) [FAIL]
  clk_hdmi: 72.221 MHz vs 74.25 MHz constraint (-2.029) [FAIL]
  clk_108m: 159.744 MHz vs 107.991 MHz constraint (+51.753) [ok]
  ...

And a comparison between two builds of the same design:

Resource changes
  LUT,ALU,ROM16                13361 ->   13450  +89 (+0.67%)
  BSRAM                           33 ->      44  +11 (+33.33%)
  CLS                           8912 ->    8901  -11 (-0.12%)

fMax changes
  clock_54m          50.404 ->    45.284 MHz  -5.12
  clock_audio       411.534 ->     437.8 MHz  +26.266

Violations: 0 introduced, 0 fixed, 1 persisting
  still  setup clock_54m -1.615ns

VERDICT: no regression.

What it reads

<name>.tr.html is only a ~350-byte frameset wrapper — the data is in the _tr_content sibling.

Tables are parsed structurally (tr/td), not by flattening the HTML, so a column layout change between tool versions surfaces as a missing field rather than a silently misaligned number.

Scope

This server reads results. It does not run builds.

A GW5A place & route takes minutes, which does not fit an MCP request, and driving long builds through a tool call hides their output. Keep building with gw_sh, make, or the Gowin GUI as you already do — then point this at the results.

Beta status

What has actually been exercised:

Known gaps, in rough order of how likely they are to bite you:

• Only the proprietary Gowin EDA flow. Output from the open-source chain (yosys / nextpnr-himbaechel / apicula) is a completely different format and is not parsed at all. If you build with nextpnr, this server has nothing to read.

• GW1N is untested. It should work — the report layout looks family-independent — but nobody has run it.

• Report headers have already been seen to drift between releases (PnR Version became Tool Version around 1.9.11). Other fields may drift the same way on versions not listed above.

• Only tested against English-language reports.

• Power and pin reports (*.power.html, *.pin.html) are written by the tool but not read yet.

Failures should be visible rather than silent: fields that do not parse come back absent instead of wrong. If you get a missing or implausible number, please open an issue with the offending .rpt.txt or _tr_content.html attached.

Notes

• Setup and hold violations are taken from the Total Negative Slack summary rather than the path tables, because the path tables are capped by -max_paths at report time and would under-report a design with many failures.

• An fMax failure is only reported separately when no setup violation already covers that clock — otherwise it is the same defect counted twice.

License

MIT