@zesun33/mcp-verilog

Model Context Protocol (MCP) server for Verilog and SystemVerilog hardware development.

mcp-verilog provides structured, token-efficient tool APIs so AI coding agents and IDEs (Cursor, Windsurf, GitHub Copilot / OpenAI Codex, Claude Code, Google Antigravity, OpenCode, Cline) can lint, syntax-check, and simulate Verilog designs in closed-loop workflows without blowing context windows on unstructured compiler output.

⚡ Quick Tour: See It in Action

Why AI Agents Need mcp-verilog

| Without mcp-verilog (Raw Shell) | With mcp-verilog (Structured MCP) | | :--- | :--- | | Dumps 5,000 lines of raw compiler output into context | Returns < 100 tokens of clean JSON | | Agent hallucinates line numbers and syntax bugs | Direct file/line jump: "line": 9, "severity": "error" | | Broken while(1) simulation hangs the agent/IDE | Timeout kill-switch (timedOut: true) | | Requires manual host install of 5+ C++ EDA packages | Zero host install (isolated rootless Podman) |

Real Agent Scenarios in 60 Seconds

1. Probing the Toolchain (Zero-Config Verification)

// Tool Call: verilog_toolchain_info
{
  "runtime": "podman",
  "tools": [
    { "name": "iverilog", "available": true, "version": "Icarus Verilog version 12.0 (stable)" },
    { "name": "verilator", "available": true, "version": "Verilator 5.020" },
    { "name": "verible-verilog-lint", "available": true, "version": "v0.0-4080-ga0a8d8eb" },
    { "name": "sv2v", "available": true, "version": "v0.0.13" }
  ]
}

2. Pinpoint Syntax Diagnostics (1-Shot Repair)

// Tool Call: verilog_lint {"files": ["syntax_error.v"]}
{
  "success": false,
  "diagnostics": [
    { "file": "syntax_error.v", "line": 9, "severity": "error", "message": "syntax error at token 'end'" }
  ]
}

3. Closed-Loop Testbench Simulation (318ms)

// Tool Call: verilog_simulate {"files": ["counter.v", "counter_tb.v"], "top_module": "counter_tb"}
{
  "success": true,
  "exitCode": 0,
  "stdout": "PASS: Counter testbench completed successfully with count=5\n"
}

4. Instant Assertion Triage (Catches Failures Safely)

// Tool Call: verilog_simulate {"files": ["failing_tb.v"], "top_module": "failing_tb"}
{
  "success": false,
  "exitCode": 1,
  "errors": ["FATAL: failing_tb.v:11: SIMULATION_ASSERTION_FAILED: Test intentional failure."]
}

5. Waveform Summary Without a GUI (Token-Capped Toggles)

// Tool Call: verilog_wave_summary {"vcd_file": "waves.vcd"}
{
  "success": true,
  "timescale": "1ps",
  "signalCount": 12,
  "signals": [
    { "name": "wave_demo_tb.clk", "width": 1, "transitions": 28, "toggled": true }
  ]
}

6. Line Coverage via Verilator (Honest Uncovered Lines)

// Tool Call: verilog_coverage {"files": ["counter.v", "wave_demo_tb.v"], "top_module": "wave_demo_tb"}
{
  "success": true,
  "linesTotal": 24,
  "linesCovered": 21,
  "coveragePct": 87.5
}

7. Testbench Skeleton in One Call (1-Shot Harness)

// Tool Call: verilog_generate_tb {"files": ["counter.v"], "top_module": "counter"}
{
  "success": true,
  "testbenchModule": "counter_tb",
  "clockPort": "clk",
  "resetPort": "rst"
}

Tools Exposed

| Tool | Parameters | Engine | Description | | :--- | :--- | :--- | :--- | | verilog_lint | files: string[], ruleset?: string, cwd?: string | verible-verilog-lint | Analyzes code style and syntax, returning structured line, column, severity, and rule diagnostics. | | verilog_compile | files: string[], top_module?: string, compiler?: "iverilog" \| "verilator", cwd?: string | iverilog / verilator | Elaboration and syntax checking without running a full simulation. | | verilog_simulate | files: string[], top_module?: string, timeout_ms?: number, dump_waves?: boolean, cwd?: string | iverilog + vvp | Compiles and executes a behavioral testbench, capturing runtime $fatal assertions, errors, and timing out runaway loops. | | verilog_wave_summary | vcd_file: string, max_signals?: number, cwd?: string | VCD parser | Summarizes a VCD file as per-signal toggle counts, time range, and timescale (no GUI needed). | | verilog_coverage | files: string[], top_module: string, timeout_ms?: number, cwd?: string | verilator --coverage + verilator_coverage | Builds the $finish-terminated testbench with Verilator coverage and reports per-file covered/total lines plus uncovered line numbers. | | verilog_generate_tb | files: string[], top_module: string, cycles?: number, output_file?: string, cwd?: string | Port parser | Generates a clock/reset harness testbench skeleton with DUT instantiation, VCD dump, and a TODO for assertions. | | verilog_toolchain_info | none | Probe | Returns the active runtime (podman, docker, host) and installed toolchain versions. |

Execution Runtime

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

Public install (recommended — anyone can pull):

podman pull ghcr.io/zesun33/verilog:latest
export MCP_VERILOG_IMAGE=ghcr.io/zesun33/verilog

ghcr.io/zesun33/verilog is the default (anyone can pull). Local builds still work as localhost/zesun33/verilog via MCP_VERILOG_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_VERILOG_RUNTIME=host

Universal Client & AI IDE Setup

Because mcp-verilog 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": {
    "verilog": {
      "command": "node",
      "args": ["/path/to/personal-projects/mcp-verilog/dist/index.js"]
    }
  }
}

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

Add to your VS Code MCP settings or user settings:

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

3. Claude Desktop & Claude Code

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "verilog": {
      "command": "node",
      "args": ["/path/to/personal-projects/mcp-verilog/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       # Unit tests (regex parsers & contract)
npm test                # All tests (including Podman integration)