@zesun33/mcp-yosys

Model Context Protocol (MCP) server for open-source RTL synthesis, cell statistics, and latch triage via Yosys.

mcp-yosys equips AI coding agents and IDEs (Cursor, Windsurf, GitHub Copilot / OpenAI Codex, Claude Code, Google Antigravity, OpenCode, Cline) with structured tools to synthesize Verilog/SystemVerilog designs, inspect cell hierarchies, and triage synthesis hazards (such as unintended transparent latches and combinational loops) before committing code to ASIC or FPGA physical design flows.

⚡ Quick Tour: See It in Action

Why AI Agents Need mcp-yosys

| Without mcp-yosys (Raw Yosys CLI) | With mcp-yosys (Structured MCP) | | :--- | :--- | | Dumps 500+ lines of techmap & ABC logs into context | Structured JSON with < 100 tokens of clean metrics | | Inferred latches buried in intermediate RTLIL logs | Pinpointed latch alerts: "variable": "q", "line": 8 | | Agent blindly guesses gate count and area footprint | Direct cell breakdown ($_AND_, $_DFF_P_, $_XOR_) | | Unresolved blackboxes silently fail downstream P&R | Explicit missingModules validation | | Requires manual installation of Yosys, ABC, and libs | Zero host configuration (runs via isolated rootless Podman) |

Real Agent Scenarios in 60 Seconds

1. Probing the Environment (Zero-Config Verification)

// Tool Call: yosys_toolchain_info
{
  "runtime": "podman",
  "image": "ghcr.io/zesun33/asic",
  "yosysVersion": "Yosys 0.38+92 (git sha1 84116c9a3)",
  "availableTargets": ["generic", "ice40", "xilinx", "intel", "sky130", "nangate45"]
}

2. Instant Latch Detection & Triage (130ms)

// Tool Call: yosys_check_latch {"verilog_sources": ["latch_demo.v"], "top_module": "latch_demo"}
{
  "success": true,
  "hasLatches": true,
  "latches": [
    {
      "module": "latch_demo",
      "variable": "q",
      "line": 8,
      "rawMessage": "Latch inferred for signal `\\latch_demo.\\q' from process `\\latch_demo.$proc$latch_demo.v:8$1'"
    }
  ],
  "hasCombinationalLoops": false,
  "warnings": [
    "Latch inferred for signal `\\latch_demo.\\q' from process `\\latch_demo.$proc$latch_demo.v:8$1': $auto$proc_dlatch.cc:433:proc_dlatch$15"
  ]
}

3. Gate-Level Synthesis & Cell Accounting (220ms)

// Tool Call: yosys_synthesize {"verilog_sources": ["counter.v"], "top_module": "counter", "target": "generic"}
{
  "success": true,
  "topModule": "counter",
  "target": "generic",
  "cellCount": 10,
  "cellsByType": {
    "$_AND_": 2,
    "$_DFFE_PN0P_": 4,
    "$_NOT_": 1,
    "$_XOR_": 3
  },
  "wireCount": 8,
  "warnings": [],
  "errors": []
}

4. Design Hierarchy & Blackbox Inspection (140ms)

// Tool Call: yosys_hierarchy {"verilog_sources": ["hierarchy_demo.v"], "top_module": "alu_top"}
{
  "success": true,
  "topModule": "alu_top",
  "modules": [
    { "name": "alu_top", "isTop": true, "submodules": ["adder", "sub"] },
    { "name": "adder", "isTop": false, "submodules": [] },
    { "name": "sub", "isTop": false, "submodules": [] }
  ],
  "missingModules": []
}

Tools Exposed

| Tool | Parameters | Engine | Description | | :--- | :--- | :--- | :--- | | yosys_synthesize | verilog_sources: string[], top_module: string, target?: "generic" \| "ice40" \| "xilinx" \| "intel" \| "sky130" \| "nangate45", flatten?: boolean, output_netlist?: string, cwd?: string, timeout_ms?: number | yosys synth | Synthesizes RTL design to generic gates, iCE40/Xilinx/Intel FPGAs, Nangate45 standard cells, or Sky130 (sky130_fd_sc_hd, with areaUm2), returning structured cell counts. sky130 needs a host-side volare PDK (MCP_YOSYS_PDK_ROOT, tt_100C_1v80 corner) and errors honestly without one. | | yosys_write_spice | netlist_file: string, top_module: string, liberty_file?: string, output_spice?: string, cwd?: string | PDK models + netlist parser | Converts a synthesized gate-level netlist to a hierarchical SPICE schematic for Netgen LVS: .includes the PDK cell models, orders cell pins per the models, ties unconnected supply pins (VPWR/VGND/VPB/VNB) to global supplies. Needs the Sky130 PDK; errors honestly otherwise. | | yosys_check_latch | verilog_sources: string[], top_module: string, cwd?: string, timeout_ms?: number | yosys check | Fast RTL elaboration pass to detect inferred transparent latches, combinational loops, and multiple drivers with source line numbers. | | yosys_equiv | gold_sources: string[], gate_netlist: string, top_module: string, cwd?: string, timeout_ms?: number | equiv_make -make_assert + sat -verify | Proves combinational equivalence (EQUIVALENT / NOT_EQUIVALENT / INCONCLUSIVE; sequential and latch designs report INCONCLUSIVE, never a false pass). | | yosys_hierarchy | verilog_sources: string[], top_module: string, cwd?: string, timeout_ms?: number | yosys hierarchy | Analyzes module instantiation tree and verifies that no submodules or blackboxes are missing. | | yosys_toolchain_info | none | Probe | Returns active container/host runtime and Yosys synthesis engine version. |

Execution Runtime

mcp-yosys runs inside the zesun33/asic rootless Podman image so tools are identical on any Linux host.

Public install (recommended — anyone can pull):

podman pull ghcr.io/zesun33/asic:latest
export MCP_YOSYS_IMAGE=ghcr.io/zesun33/asic

ghcr.io/zesun33/asic is the default (anyone can pull). Local builds still work as localhost/zesun33/asic via MCP_YOSYS_IMAGE.

• Container mount: -v <workspace>:/workspace:Z -w /workspace
• Podman storage option: --storage-opt overlay.ignore_chown_errors=true

To force host binaries instead of container execution:

export MCP_YOSYS_RUNTIME=host

Other useful overrides:

export MCP_YOSYS_IMAGE=ghcr.io/zesun33/fpga    # FPGA image instead of ASIC

Universal Client & AI IDE Setup

Because mcp-yosys implements the standard Model Context Protocol (MCP), it connects seamlessly to any MCP-compliant AI IDE or agent interface:

| Environment | Supported Tools | Setup Location | | :--- | :--- | :--- | | AI IDEs | Cursor, Windsurf, Google Antigravity, Zed | .cursor/mcp.json or .windsurf/mcp.json | | Extensions | GitHub Copilot / OpenAI Codex, Cline, Roo Code | VS Code MCP extension settings | | CLI Agents | Claude Code, OpenCode, Goose, Antigravity CLI (agy) | Global MCP configuration or CLI flags | | Desktop | Claude Desktop | claude_desktop_config.json |

1. Cursor / Windsurf / Antigravity IDE

Add to your project's .cursor/mcp.json or .windsurf/mcp.json:

{
  "mcpServers": {
    "yosys": {
      "command": "node",
      "args": ["/path/to/personal-projects/mcp-yosys/dist/index.js"]
    }
  }
}

2. VS Code (GitHub Copilot / OpenAI Codex / Cline)

Add to your VS Code MCP settings or user configuration:

{
  "mcpServers": {
    "yosys": {
      "command": "node",
      "args": ["/path/to/personal-projects/mcp-yosys/dist/index.js"]
    }
  }
}

3. Claude Desktop & Claude Code

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "yosys": {
      "command": "node",
      "args": ["/path/to/personal-projects/mcp-yosys/dist/index.js"]
    }
  }
}

Verification & Testing

Run the full 6-gate verification suite:

# Full verification (with Podman container execution)
./scripts/verify.sh

# Fast / CI verification (headless environments)
./scripts/verify.sh --quick

Run specific test tiers:

npm run test:unit       # Fast unit tests (parsers & contract)
npm test                # Full test suite (including live container synthesis)