Gowin MCP

Local MCP server for Gowin builds, reports, programming and board measurements. Vendor tools stay on the host. Each build gets its own source snapshot, logs, configuration and artifact hashes.

Install

Python 3.11+:

python -m venv .venv
# Linux/macOS
.venv/bin/python -m pip install -r requirements.txt
# Windows
.venv/Scripts/python.exe -m pip install -r requirements.txt

Launch gowin_lab.py with that Python interpreter over stdio. Set GOWIN_WORKSPACE to your FPGA repository and GOWIN_HOME to the Gowin install. The default workspace is the process's current directory. Supported project locations are 0*/gowin*/*.gprj and tangnano20k/*/*.gprj. Projects need impl/project_process_config.json with their top module. Declared sources must resolve inside the chosen workspace.

An npm launcher is also available:

npx @eoinedgenpm/gowin-mcp --check
npx @eoinedgenpm/gowin-mcp

Set GOWIN_PYTHON to the prepared virtual environment interpreter if needed. The launcher checks Python and dependencies; it does not install Python or modify your Python environment automatically. Set the same workspace/vendor environment variables as for direct Python launch.

For a local Codex client, replace these paths with your checkout and interpreter:

codex mcp add gowin --env GOWIN_WORKSPACE=C:\Users\Eoin\git\GBA-FPGA --env GOWIN_HOME=C:\Gowin\Gowin_V1.9.12.04_x64 -- C:\Python313\python.exe C:\path\to\gowin-mcp\gowin_lab.py

The registration command is documented in OpenAI's MCP guide. Other clients can launch the same command, arguments and environment using their stdio-server configuration.

Tools

| Tools | Purpose | |---|---| | environment, projects | Discover tools, serial interfaces, free space and project manifests | | prepare_run, edit_variant | Snapshot a project and edit RTL/constraints in isolation | | run_phase, run_status, cancel_job | Run synthesis, place/route or the complete flow; collect logs and artifacts | | read_artifact, read_report_tables | Read reports with original labels, units and hashes | | scan_cables, scan_chain | Identify the cable and FPGA before deployment | | program_sram | Program one selected target with a matching bitstream SHA256 | | capture_gao | Acquire internal digital signals through a matching GAO debug core | | capture_logic, analyze_vcd | Capture with sigrok and count known digital transitions | | analyze_csv, record_measurement | Analyze external scope/power exports or record operator readings | | compare_runs | Compare phase durations, source identity, reports and physical measurements separately |

See the programmer and measurement workflow and the Nano 20K handheld assessment.

Platform and device support

The server uses portable Python and is tested on Windows, Linux and macOS. Local Gowin compilation requires a vendor-supported host and working license. macOS can use report/capture analysis and programming tools that support the attached device; installing this server does not add a macOS Gowin compiler.

GAO and Power Analyzer are different instruments: GAO captures digital signals, and Power Analyzer estimates power. Neither provides measured supply voltage. FNIRSI scopes and Bus Pirate revisions need exact model/protocol details before direct control is implemented. Scope CSV import and manual measurement records are available now. Sigrok capture requires a supported device driver.

No arbitrary shell/Tcl execution, flash erase, supply setpoints or Bus Pirate pin-mode changes are exposed. One service process should own each workspace.

Tests

python test_gowin_lab.py

Tests exercise actual MCP calls and subprocess behavior using fixtures. Vendor builds were separately verified on Windows with Gowin V1.9.12.04 for ten Tang Nano 20K teaching projects and the GBA-FPGA LCD test. Hardware captures and programming have not yet been verified through this server.

MIT license. Gowin software and upstream console cores retain their own licenses.