@zesun33/mcp-cocotb

Purpose and first steps

Run Python hardware testbenches and inspect their results through an MCP server.

Who it is for: Hardware engineers using an MCP-capable client or coding agent.

First task: Configure the server in your MCP client, then call cocotb_toolchain_info before running a design.

What to expect: Simulator/tool availability, then discovered tests and parsed pass/fail results.

Current scope: Published MCP server. The npx command starts a stdio server that waits for a client; EDA execution also needs its documented host/container tools.

Start here: Runtime requirements and configuration.

Related projects: mcp-verilog, hw-verification-suite.

Choose another project.

Model Context Protocol (MCP) server for Python-based Cocotb co-simulation hardware testbenches.

mcp-cocotb equips AI coding agents and IDEs (Cursor, Windsurf, GitHub Copilot / OpenAI Codex, Claude Code, Google Antigravity, OpenCode, Cline) with structured tools to discover, generate, and run asynchronous Python testbenches against Verilog/SystemVerilog designs. By wrapping the complexity of simulator VPI compilation, Makefile orchestration, and JUnit XML parsing into deterministic JSON contracts, agents can execute closed-loop verification without drowning in simulator logs.

Related MCP server: EDA Tools MCP Server

Install and run

Run this MCP server directly from npm:

npx -y @zesun33/mcp-cocotb

For the complete hardware-agent setup, use npx -y @zesun33/create-hw-agent my-asic.

⚡ Quick Tour: See It in Action

The examples below illustrate tool requests and result fields. Timings, counts, and scores depend on the input and runtime; they are not guaranteed outcomes or fresh verification results.

Why AI Agents Need mcp-cocotb

Example tool requests and results

1. Probing the Environment (Zero-Config Verification)

// Tool Call: cocotb_toolchain_info
{
  "runtime": "podman",
  "image": "ghcr.io/zesun33/verilog",
  "cocotbVersion": "2.1.0",
  "pythonVersion": "Python 3.12.3",
  "simulator": "iverilog (Icarus Verilog)"
}

2. Static Test Discovery (Inspect Test Matrix Without Running)

// Tool Call: cocotb_list_tests {"test_file": "test_dff.py"}
{
  "file": "test_dff.py",
  "totalTests": 3,
  "tests": [
    { "name": "test_dff_reset", "doc": "Verify DFF reset behavior." },
    { "name": "test_dff_toggle", "doc": "Verify DFF data propagation across clock edges." },
    { "name": "test_dff_failing_assert", "doc": "Negative test fixture for assertion failure handling." }
  ]
}

3. Automated Co-Simulation Runner (Passing Suite)

// Tool Call: cocotb_run {"verilog_sources": ["dff.v"], "toplevel": "dff", "python_module": "test_dff"}
{
  "success": false,
  "totalTests": 3,
  "passedTests": 2,
  "failedTests": 1,
  "durationSeconds": 0.04,
  "tests": [
    { "name": "test_dff_reset", "classname": "test_dff", "time": 0.012, "status": "pass" },
    { "name": "test_dff_toggle", "classname": "test_dff", "time": 0.018, "status": "pass" },
    {
      "name": "test_dff_failing_assert",
      "classname": "test_dff",
      "time": 0.010,
      "status": "fail",
      "failureMessage": "assert False, 'INTENTIONAL_ASSERTION_FAILURE'",
      "traceback": "Traceback (most recent call last):\n  File \"test_dff.py\", line 45, in test_dff_failing_assert\n    assert False, 'INTENTIONAL_ASSERTION_FAILURE'\nAssertionError: INTENTIONAL_ASSERTION_FAILURE"
    }
  ]
}

4. Instant Agent Self-Repair Loop

Because mcp-cocotb captures the exact Python failure traceback (AssertionError: INTENTIONAL_ASSERTION_FAILURE at line 45), the LLM agent immediately knows what line and condition failed and can self-correct the RTL or testbench in a single turn without human intervention.

Tools Exposed

Execution Runtime

mcp-cocotb 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_COCOTB_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_COCOTB_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_COCOTB_RUNTIME=host

Universal Client & AI IDE Setup

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

1. Cursor / Windsurf / Antigravity IDE

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

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

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

Add to your VS Code MCP settings or user configuration:

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

3. Claude Desktop & Claude Code

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "cocotb": {
      "command": "node",
      "args": ["/path/to/personal-projects/mcp-cocotb/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 & AST discovery)
npm test                # Full test suite (including live container simulation)

npm releases

See RELEASING.md for GitHub Actions dry runs and trusted publishing.