@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)