Pyslang MCP
pyslang-mcp is a read-only Model Context Protocol server for compiler-backed Verilog and SystemVerilog analysis. It uses pyslang to parse HDL projects, report diagnostics, inspect design units and hierarchy, and expose structured semantic information to AI tools.
Ask AI about Pyslang MCP
Powered by Claude · Grounded in docs
I know everything about Pyslang MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
pyslang-mcp
pyslang-mcp is a local Model Context Protocol server that gives AI agents
compiler-backed, read-only context for Verilog and SystemVerilog projects.
It wraps pyslang so an MCP client can ask
questions against parsed and elaborated HDL instead of plain text:
- What modules, interfaces, and packages are in this filelist?
- What diagnostics does the compiler frontend report?
- What is the instance hierarchy below this top?
- Where is this symbol declared or referenced?
- Did my include paths, defines, and nested
.ffiles resolve as expected?
This is not a simulator, synthesizer, waveform viewer, linter replacement, or RTL refactoring tool. It is a small semantic analysis service for local HDL checkouts.
[!NOTE] The project is currently alpha and published on PyPI and the MCP Registry for local stdio use. Install with
--prewhile the package uses alpha versions.
Why ASIC And EDA Engineers Might Care
Most AI coding tools are good at searching text. HDL usually needs more than that.
In real projects, useful answers often depend on filelists, packages, includes,
defines, generate blocks, and hierarchy. pyslang-mcp gives an agent a compact
compiler-backed view of that structure, while keeping the server read-only and
scoped to a project root you provide.
Good fits:
- triaging parse and semantic diagnostics before asking an agent to reason about RTL
- checking what a
.ffile expands to - listing design units in a block or small IP
- finding a declaration without chasing comments and stale grep hits
- getting hierarchy and port-connection context for review/debug prompts
- giving workflow agents HDL context without handing them an EDA runtime
Quickstart
Install the alpha package:
pip install --pre pyslang-mcp
Run the local stdio server:
pyslang-mcp
For contributor setup, clone the repo and install it in editable mode:
git clone https://github.com/ariklapid/pyslang-mcp.git
cd pyslang-mcp
python -m venv .venv
./.venv/bin/pip install -e '.[dev]'
Run the checkout stdio server:
./.venv/bin/python -m pyslang_mcp
The installed console script works too:
./.venv/bin/pyslang-mcp
Run tests:
./.venv/bin/pytest
MCP Client Config
Use local stdio. The MCP client should launch the server on the same machine,
VM, or dev container that can see your RTL checkout.
{
"mcpServers": {
"pyslang-mcp": {
"command": "pyslang-mcp",
"args": []
}
}
}
For editable checkout installs, point the command at the checkout virtual environment instead:
{
"mcpServers": {
"pyslang-mcp": {
"command": "/absolute/path/to/pyslang-mcp/.venv/bin/python",
"args": ["-m", "pyslang_mcp"]
}
}
}
Tool calls must provide a project_root. Source paths, filelists, and include
directories may be absolute or relative, but they must stay under that root.
Minimal Tool Payloads
Analyze explicit files:
{
"project_root": "/path/to/rtl-project",
"files": ["rtl/pkg.sv", "rtl/top.sv"],
"include_dirs": ["include"],
"defines": {
"WIDTH": "32"
},
"top_modules": ["top"]
}
Analyze a filelist:
{
"project_root": "/path/to/rtl-project",
"filelist": "compile/project.f"
}
Find a symbol:
{
"project_root": "/path/to/rtl-project",
"filelist": "compile/project.f",
"query": "payload",
"match_mode": "exact",
"include_references": true
}
Tools
| Need | Tool |
|---|---|
| Load explicit files | pyslang_parse_files |
Load a .f filelist | pyslang_parse_filelist |
| Get parse and semantic diagnostics | pyslang_get_diagnostics |
| List modules, interfaces, and packages | pyslang_list_design_units |
| Inspect one design unit | pyslang_describe_design_unit |
| Walk the elaborated instance tree | pyslang_get_hierarchy |
| Find declarations and references | pyslang_find_symbol |
| Summarize syntax node shapes | pyslang_dump_syntax_tree_summary |
| Check preprocessing metadata and excerpts | pyslang_preprocess_files |
| Get a compact project overview | pyslang_get_project_summary |
Typical flow:
- Start with
pyslang_parse_filelistorpyslang_parse_files. - Run
pyslang_get_diagnostics. - Use
pyslang_list_design_unitsto see what the compiler frontend found. - Use
pyslang_describe_design_unit,pyslang_get_hierarchy, orpyslang_find_symbolfor the actual review/debug question.
Filelist Support
The current parser intentionally supports a practical subset used by many RTL flows:
- source file entries
- nested filelists with
-fand-F - include directories with
+incdir+...,-I dir, and-Idir - defines with
+define+...,-D NAME, and-DNAME
Unsupported filelist tokens are reported in the tool output instead of being silently ignored.
Example Agent Prompts
Use this server when compiler-backed context matters:
- "Parse
compile/project.fwith+define+DEBUGand group diagnostics by source file." - "List every design unit in this project and identify the likely top modules."
- "From
top, show the instance hierarchy down to depth 4." - "Describe module
axi_dma_top: ports, child instances, and declared names." - "Find the declaration and references for
payload_valid." - "Confirm whether
legacy_widgetis instantiated anywhere the elaborator sees it." - "Show the resolved files, include dirs, defines, and unsupported entries from this filelist."
For single-line questions, comments, naming searches, or partial/incomplete
source sets, regular rg, editor search, or direct file reading is usually
faster and clearer.
Guardrails
- Read-only MCP tools. No RTL edits, formatting, simulation, or synthesis.
- Strict project-root scoping. Paths outside
project_rootare rejected. - Compact JSON responses with truncation metadata for large result sets.
- Process-local cache keyed by project config and tracked file mtimes.
pyslang_preprocess_filesis summary-oriented. It returns preprocessing metadata and source excerpts, not a guaranteed full standalone preprocessed stream.streamable-httpexists only as an explicit experimental local transport; it is not a secure hosted deployment mode.
HDL Example Corpus
The repo includes generated HDL examples under
examples/hdl:
- clean reference projects from single modules to small IP-style examples
- intentionally buggy variants labeled
easy,medium, andhard - local validation hooks for both
pyslangandverilator --lint-only
Run the full corpus validator:
./.venv/bin/python scripts/validate_hdl_examples.py
Run the CI smoke subset:
./.venv/bin/python scripts/validate_hdl_examples.py --smoke-only
Project Status
Implemented:
FastMCPstdio server- CLI entrypoint via
python -m pyslang_mcpandpyslang-mcp - project loader with root checks and
.fparsing - pyslang-backed diagnostics, design-unit listing, hierarchy, symbol lookup, syntax summaries, and project summaries
- bounded in-memory cache
- fixture-backed tests and Ubuntu CI for Python 3.11 and 3.12
- package smoke CI from a built wheel
- manual PyPI Trusted Publishing release workflow with release-gate tests
- PyPI alpha release line:
pyslang-mcp - MCP Registry entry:
io.github.ariklapid/pyslang-mcp
Not done yet:
- schema freeze for a non-alpha release
- broad platform validation beyond the current Linux-focused CI path
Development
Useful commands:
./.venv/bin/ruff check .
./.venv/bin/pyright
./.venv/bin/pytest
Architecture and contribution docs:
License
Apache-2.0. See LICENSE.
