vunit-mcp
It is an MCP server that lets an LLM/agent drive a VUnit HDL unit-testing project end to end.
Inspect the project: report server config/simulator availability (
vunit_status), list all tests (vunit_list_tests), and list source files in compile order (vunit_list_files).Build and run: compile all sources (
vunit_compile) and run tests with patterns, threads, clean builds, timeouts, and attribute filters (vunit_run_tests), returning pass/fail summaries and failing test names.Debug failures: re-read the last JUnit report (
vunit_get_report) to see which tests passed/failed, and fetch a single test's log tail with parsed check results (vunit_get_test_log).Analyze waveforms: after running with a waveform format, resolve the recorded waveform file path plus failing-check sim time (
vunit_get_test_waveform) for handoff to a waveform-reading tool.Understand dependencies: get the ordered source files needed to implement a specific test (
vunit_test_dependencies) and export the full project model as JSON (vunit_export_json).No simulator needed for status, listing, report/log/waveform lookup, dependency analysis, or export; only compile/run require a simulator.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@vunit-mcp list the tests in the project and run the failing ones"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
vunit-mcp
MCP (stdio) server that lets an LLM/agent drive a VUnit (HDL
unit-testing) project end to end: list tests, compile, run, and inspect
reports, per-test logs, and — for GHDL runs (and NVC on a VUnit with the
headless --wave flag) — record signal waveforms and hand the file path
off to a waveform-reading MCP server.
VUnit has no standalone CLI and VUnit.main() calls sys.exit(), so the
server never runs vunit in-process — it shells out to the project's own
run.py, exactly how a human runs it. The server installs no VUnit at
all: the only VUnit that ever answers a question is the project's own, so
the answers cannot disagree with what the project actually compiles. Even
vunit_test_dependencies ("which files do I need to implement this
test?"), which needs VUnit internal API with no CLI equivalent, runs as a
subprocess under the project's interpreter — see Dependency
probe.
Setup
uv venv .venv
uv pip install -e . # installs vunit-mcp + mcp + pydantic — no vunitVUnit itself belongs to the project, not here. Compile/run also need a
simulator (ghdl, nvc, …) on the PATH of the interpreter that runs
run.py — the project venv, which the server creates and activates for you
(see Project virtualenv).
Waveforms need --wave in the project's VUnit
Headless waveform recording (waveform_format) needs the --wave flag
from upstream PR #1101, which
no released VUnit has yet. Since the server ships no VUnit, whether
waveforms work is decided entirely by what the project installs:
Project's VUnit | GHDL | NVC |
has | vcd, headless | fst, headless |
stock (no | vcd/ghw via the legacy | nothing recorded — the run says so |
vunit_status reports whether the flag is there, and the tool docs tell
the LLM to check it before promising a waveform.
On a VUnit 5.0 prerelease one project-side change applies: VUnit 5 no
longer compiles the HDL builtins by default, so a 4.x-style run.py must
add PROJ.add_vhdl_builtins() after VUnit.from_argv() (VUnit prints the
exact line to add if it is missing).
Related MCP server: vivado-mcp
Configuration (env vars)
Variable | Meaning | Default |
| dir containing | server's cwd |
| run script path relative to project dir |
|
| interpreter that runs | the project venv's own python (see below) |
| create a missing project venv with uv ( | enabled |
|
|
|
| max seconds for venv creation + dependency install |
|
| passed through as | VUnit auto-detect |
| default |
|
| max seconds per run/compile |
|
| extra | unset |
| comma-separated patterns (fnmatch globs on file name or project-relative path, or a directory name) of registered files whose content changes must not invalidate the export cache — for generated/volatile files; adding or removing them still does | unset (fingerprint everything) |
Project virtualenv
The project's own virtualenv is always used and activated for every
run.py subprocess — VIRTUAL_ENV set, <venv>/bin first on PATH,
PYTHONHOME cleared, and this server's own venv removed from the
environment — so nested python/pip/console-script lookups made by
run.py itself resolve inside it, not just the top-level interpreter.
Resolution order at startup:
VUNIT_MCP_PYTHON, if set (authoritative; when it points into a venv, that venv is activated too, and nothing is ever created).An existing
<project>/.venv, else<project>/venv.Otherwise one is created with
uv, from whichever of the project's dependency declarations works:uv syncfor apyproject.toml, elseuv venv+uv pip install -r requirements.txt, elseuv venv+uv pip install -r pyproject.toml(a pyproject that only carries tool config falls through torequirements.txtinstead of failing the run).If the project declares no dependencies, or
uvis not installed, the old behavior applies:python3/pythonfromPATH(this server's own venv excluded), andvunit_statusreports why.
Several agents on one code base
vunit_run_tests is serialized by an in-process lock, so one server per agent
removes the only interlock there is. Concurrent run.py invocations share
<project>/vunit_out (compiled libraries, test_output/, junit.xml) and will
clobber each other. Either give each agent its own VUNIT_MCP_OUTPUT_DIR, or —
simpler and fully disjoint — give each agent its own git worktree and start
the server with that worktree as cwd; output dir, venv, export cache and git
index are then separate with no configuration. Venv provisioning is safe
either way: discovery and creation happen under a cross-process lock keyed on
the project path (shared with tsfpga-mcp, which provisions the same venv), so a
server that arrives mid-install waits for the real thing instead of adopting a
virtualenv that has an interpreter but not yet any packages.
MCP client config (Claude Code)
The server has runtime dependencies (mcp, pydantic), so run it with
uvx rather than a raw venv binary — it resolves and installs them into an
isolated environment for you:
{
"mcpServers": {
"vunit": {
"command": "uvx",
"args": ["--from", "/path/to/vunit-mcp", "vunit-mcp"],
"env": {
"VUNIT_MCP_PROJECT_DIR": "/path/to/your/vunit/project"
}
}
}
}--from accepts a local checkout path or a git URL
(--from "vunit-mcp @ git+https://github.com/<owner>/vunit-mcp.git").
A local checkout is installed by content hash, so edits to the server are
picked up automatically; uvx --refresh forces a re-resolve.
VUNIT_MCP_PROJECT_DIR is optional — it defaults to the server's current
working directory — but most MCP hosts launch servers from an arbitrary
directory, so set it explicitly unless you know the host's cwd is the
project.
Or with MCP Inspector for manual testing:
VUNIT_MCP_PROJECT_DIR=/path/to/project npx @modelcontextprotocol/inspector \
uvx --from /path/to/vunit-mcp vunit-mcpSkill
This repo ships an agent skill, skills/vunit-mcp/SKILL.md, that tells the
LLM when and how to use the tools: which tool answers which request,
workflow recipes ("why did test X fail?" → vunit_get_test_log), the
lib.entity[.test_case] test-name format, and the VUNIT_MCP_* configuration.
Install it next to the server so the agent picks it up automatically.
Claude Code
Symlinking keeps the repo checkout as the single source of truth (copy with
cp -r if you prefer a static install):
# personal — available in every project
ln -s /path/to/vunit-mcp/skills/vunit-mcp ~/.claude/skills/vunit-mcp
# or project-local — available only in that project
mkdir -p <your-project>/.claude/skills
ln -s /path/to/vunit-mcp/skills/vunit-mcp <your-project>/.claude/skills/vunit-mcpMaki
Maki loads skills from the same ~/.claude/skills/ directory:
ln -s /path/to/vunit-mcp/skills/vunit-mcp ~/.claude/skills/vunit-mcpTools
Tool | Needs sim | Description |
| no | config, vunit version, simulator availability — call first |
| no | all tests ( |
| no | source files in compile order via |
| yes | compile all sources ( |
| yes | elaborate test benches without running ( |
| yes | run tests (patterns, threads, clean, …); writes JUnit XML; returns pass/fail summary + failing tests. |
| no | answers which tests passed/failed — re-reads the last run's JUnit XML, no re-run, safe to call repeatedly; per-test status + failing-check counts; use it to pick a test before reading its log. |
| no | answers why one test failed — the single test's |
| no | resolves the test's recorded waveform file (requires |
| no | ordered list of source files needed to implement one test (grouped by library, compile order, VUnit built-ins summarized); caches a project model in |
| no | project files, tests, and attributes via |
Export cache
vunit_export_json and vunit_test_dependencies do not re-run
run.py --export-json on every call: the exported model is written to
<project>/.vunit-mcp-cache/export.json together with a fingerprint of its
inputs, and served from that file while the fingerprint matches. The cache
invalidates when:
any registered source file's mtime or size changes, or the file disappears;
run.pyitself changes (covers adding/removing/relocating files);VUNIT_MCP_PYTHON,VUNIT_MCP_SIMULATOR, orVUNIT_MCP_EXTRA_ARGSchange.
Files matching VUNIT_MCP_FINGERPRINT_EXCLUDE (comma-separated fnmatch
globs on file name or project-relative path, or a directory name) are
exempt from the first rule — their mtime/size are not tracked, for
generated or volatile files whose rewrites would churn the cache. Their
name and existence are still tracked, so adding or removing one
invalidates as usual.
To force a fresh export, delete .vunit-mcp-cache/export.json. Dependency
answers are cached additionally, in memory, keyed by export content and
test name.
Dependency probe
Some VUnit questions cannot be answered through the project's own run.py
CLI — e.g. "which files do I need to implement this test?", which needs
VUnit's internal get_implementation_subset. Importing VUnit in the server
would answer it with the wrong VUnit, so instead dependency_probe.py is
executed as a script by the project's interpreter:
<project venv python> dependency_probe.py # request JSON on stdinIt is deliberately self-contained — stdlib + vunit only, never importing
vunit_mcp, since the project venv has vunit-mcp installed nowhere. It
rebuilds a VUnit instance from the cached --export-json model
(libraries and source files registered), calls the internal API, and writes
its reply to <scratch>/result.json rather than stdout, because VUnit logs
to stdout/stderr with no contract that it stays quiet.
That instance is never run through the CLI: the export model lacks the
user's run.py specifics (custom options, test attributes, requirements,
…), so anything that compiles or runs must go through the project's own
run.py.
The scratch dir is <project>/.vunit-mcp-cache/model/<sha256 of export> —
never the project's vunit_out (VUnit would wipe it) and never the
.vunit-mcp-cache root (which holds export.json). VUnit leaves a pickled
project_database there and reloads it next time, which makes it a parse
cache: parsing every source file is the expensive part. That path is
predictable, so a database planted there by a hostile project would be code
execution on pickle.loads; the first probe of each key therefore wipes
any database it did not write itself, and only later probes in the same
server process reuse one.
Log-size policy
Tool output is deliberately bounded so it stays LLM-friendly — raw logs are never dumped in full:
vunit_get_test_logreturns the last 100 lines by default and says so (e.g. "showing last 100 of 3421 lines"); raiselinesfor more. Even an explicit "full" read is capped at ~24 KB (the tail of the file).vunit_compilereturns a 10-line tail on success and an error-line excerpt (error/fatal/failure lines + 2 lines of context) on failure.vunit_elaboratebehaves the same way, but performs a real GHDL elaboration pass (ghdl -e), not just per-file analysis (ghdl -a) — it catches cross-unit errors (port/generic/type mismatches between an entity and its instantiations) thatvunit_compilemisses whenever the mismatched entity isn't exercised by a currently-selected test.All other raw-output fallbacks (failed
run.py, unparseable output) are tail-truncated to 4 000 chars, keeping the end where errors and result lines live.vunit_run_tests/vunit_get_reportreturn the parsed JUnit summary (counts + failing test names) rather than raw output.vunit_export_jsoninlines the JSON only below 8 000 chars; above that it returns counts + file/test name lists.Waveforms are never read or dumped by this server:
vunit_get_test_waveformreturns the recorded file's path (plus the failing check's sim time), and the actual waveform analysis happens in a separate waveform-reading MCP server that receives that path.vunit_list_files/vunit_export_jsonlist project files only; VUnit built-in library sources (installed package files) are summarized as a count, since they are stable and not part of the project.
Development
uv pip install -e ".[dev]"
uv run pytest tests/ # pure parsers — no simulator required
uv run ruff check src/ tests/
uv run mypy src/vunit_mcp/A few tests exercise dependency_probe.py for real and need a VUnit; they
skip unless one is installed. To run them, sync the non-default e2e
dependency group — the only place vunit-hdl appears in this repo:
uv sync --group e2e
uv run pytest tests/Available Tools
9 toolsvunit_compileAIdempotent
Compile all sources in the VUnit project (--compile). Requires a simulator. Safe to re-run.
Inputs: no named parameters. Returns: result
vunit_export_jsonARead-only
Export the project model (source files, all tests, attributes) as JSON via --export-json. Attributes carry requirement/traceability data. The export is cached at .vunit-mcp-cache/export.json in the project and re-run only when the project's sources change. Does not require a simulator.
Inputs: no named parameters. Returns: result
vunit_get_reportARead-only
Re-read the last run's JUnit report from the output dir (no re-run). Returns per-test status, with the number of failing VUnit checks per test when its log shows any. Pass a failing test name to vunit_get_test_log to see why it failed.
Inputs: no named parameters. Returns: result
vunit_get_test_logARead-only
Get the log output for one test (the per-test output.txt), which is
how you see WHY a test failed. test_name is the full name from
vunit_list_tests / vunit_get_report. Returns the last 100 lines by
default (failure info appears at the end); pass a larger lines for
more context. When the log contains failing VUnit checks, a
structured "Check results" section is appended after the log.
Inputs: input (required). Returns: result
vunit_list_filesARead-only
List all source files in compile order. Does not require a simulator.
Inputs: no named parameters. Returns: result
vunit_list_testsARead-only
List all test cases (lib.entity[.proc]) the project knows about. Does not require a simulator.
Inputs: no named parameters. Returns: result
vunit_run_testsA
Run VUnit tests and return a pass/fail summary plus the list of failing tests. Patterns default to ['*'] (run everything). A JUnit XML is always written next to the output dir for vunit_get_report. Requires a simulator.
Inputs: input. Returns: result
vunit_statusARead-only
Report server configuration: project dir, run script, interpreter, VUnit version, and whether a simulator appears available. Call this first when diagnosing setup problems.
Inputs: no named parameters. Returns: result
vunit_test_dependenciesARead-only
Return the ordered list of source files needed to implement one test case: the files it depends on to elaborate, grouped by library in compile order (VUnit built-in files summarized as a count). Does not compile and needs no simulator.
Inputs: input (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool targets a distinct concern: configuration health, test listing, file listing, compilation, running, report retrieval, per-test logs, JSON export, and dependency resolution. There is no meaningful overlap even between get_report and get_test_log because one is the aggregate results summary and the other is the raw output for a single test.
All tools share the vunit_ prefix and mostly follow a verb_noun pattern (list_tests, list_files, run_tests, get_report, get_test_log, export_json). Minor deviations like vunit_status and vunit_compile are still readable and do not create confusion.
Nine tools is well-scoped for a VUnit test project workflow. Each tool covers a distinct step from inspection and compilation through running tests and debugging failures, and none feels redundant or extraneous.
The tool set covers the full practical VUnit workflow: diagnosing setup, discovering tests and files, compiling, running, retrieving aggregate results, inspecting per-test logs, exporting project data, and tracing test dependencies. There are no obvious dead ends that would prevent an agent from completing a typical build-and-debug cycle.
Maintenance
Related MCP Connectors
Manage SysML2 projects; check, evaluate, verify, query, document and diagram models.
Create and manage test cases, test runs and results in Testiny from your AI assistant.
Manage uivoid projects, tools, keys, hosted databases and teams from your agent.
Read a project's prompts, logs and agents, and send new work to the agent on your own machines.
Related MCP Servers
- FlicenseNot gradedqualityAmaintenanceEnables AI agents such as Claude Code, Cursor, and Codex to safely drive a locally installed Xilinx Vivado through 32 tools covering sessions, synthesis, implementation, timing, CDC, XDC, IP, waveforms, and device programming. Includes structured timing evidence with baseline comparison, offline VCD queries, evidence-driven workflow prompts, and one-command environment self-checks.-
- FlicenseNot gradedqualityAmaintenanceEnables AI coding agents to safely drive a locally installed Xilinx Vivado FPGA flow, covering session control, synthesis, implementation, timing and CDC analysis, XDC constraints, IP inspection, waveform queries, and device programming with structured, evidence-based diagnostics.-
- FlicenseNot gradedqualityAmaintenanceEnables AI coding agents such as Claude Code, Cursor, and Codex to drive a locally installed Xilinx Vivado through 32 curated tools covering sessions, synthesis, implementation, timing and CDC reports, XDC, IP, waveforms, and device programming. It also provides structured timing evidence with baseline comparison, offline VCD queries, environment self-diagnostics, and evidence-driven workflow prompts.-
- FlicenseNot gradedqualityAmaintenanceEnables AI agents such as Claude Code, Cursor, and Codex to safely drive a locally installed Xilinx Vivado through 32 curated tools covering sessions, synthesis, implementation, timing, CDC, XDC, IP, waveforms, and device programming. It provides structured timing evidence with baseline comparison, offline VCD queries, environment self-checks, and Chinese-language diagnostics for timing and CRITICAL WARNING issues.-