Content
# Verilog MCP Server
Verilog/SystemVerilog RTL semantic analysis MCP server. Based on tree-sitter parsing HDL source files, combined with pyslang (slang compiler frontend) for semantic-level elaboration, exposing tools such as module search, signal tracking, hierarchy tree construction, FSM detection, clock domain analysis, and visualization through the MCP protocol.
## Installation
```bash
pip install -e .
```
## Usage
```bash
# Check version
verilog-mcp-server --version
# Start MCP server (stdio transport, called by MCP client)
verilog-mcp-server
# Build index at startup
verilog-mcp-server --build -p /path/to/rtl/project
# Specify filelist file (automatically extract +incdir+ and +define+)
verilog-mcp-server --build -f project.f
# Specify top module
verilog-mcp-server --build -f project.f --top soc
# Force full rebuild
verilog-mcp-server --rebuild -p /path/to/rtl/project
```
### CLI Parameters
| Parameter | Description |
|-----------|-------------|
| `--version` | Show version number |
| `-p, --paths` | Project path to index (override configuration) |
| `-f, --filelist` | Specify .f file list path (support multiple) |
| `-t, --top` | Specify top module name |
| `--build` | Build index at startup (incremental update) |
| `--rebuild` | Force full rebuild at startup |
| `--cache` | Cache file path |
| `--log-level` | Log level (DEBUG/INFO/WARNING/ERROR) |
### MCP Client Configuration
```json
{
"mcpServers": {
"verilog": {
"command": "verilog-mcp-server",
"args": ["--build", "-f", "/path/to/project.f", "--top", "soc"]
}
}
}
```
### Offline Executable
CentOS 8.4 compatible standalone executable (no Python environment required):
```bash
# Build on CentOS 8.4
bash scripts/build-centos8.sh
# Or use pre-built tar.gz
tar xzf verilog-mcp-server-linux-x86_64.tar.gz
./verilog-mcp-server --build -f project.f --top soc
```
## MCP Tools
### Level 1 — Basic Query
| Tool | Description |
|------|-------------|
| `rtl_search_module` | Fuzzy search module name |
| `rtl_get_module` | Get module complete definition (ports, signals, parameters, instances, always blocks, assign, package/import, SVA assertions, testbench markers) |
| `rtl_module_ports` | Query module port list (direction/type/width/signed, support ANSI and non-ANSI style) |
| `rtl_list_instances` | List all submodule instances in a module |
| `rtl_search_signal` | Search cross-module signal by name |
| `rtl_search_package` | Fuzzy search package definition (name, type, parameters) |
| `rtl_search_function` | Fuzzy search function/task definition (ports, return type) |
| `rtl_hierarchy` | Recursive hierarchy tree (prefer pyslang data, include generate expansion) |
### Level 2 — Relation Analysis
| Tool | Description |
|------|-------------|
| `rtl_trace_signal` | Signal cross-module data flow tracking (fan-in backtrack drive source / fan-out track load) |
| `rtl_signal_fan_in` | Signal fan-in analysis — list all drive sources |
| `rtl_signal_fan_out` | Signal fan-out analysis — list all loads |
| `rtl_where_used` | Cross-reference — find module/signal instantiation location and usage points |
| `rtl_instance_connections` | Instantiation port connection details — formal port and actual signal mapping |
| `rtl_hierarchy_tree` | Module hierarchy tree (text format) |
| `rtl_hierarchy_instances` | Hierarchy instance list (flatten all instantiations) |
### Level 3 — Intelligent Analysis
| Tool | Description |
|------|-------------|
| `rtl_detect_fsm` | Finite state machine detection — state encoding, transfer table, Mealy/Moore classification |
| `rtl_clock_domains` | Clock domain analysis — clock signal, reset, frequency division, cross-domain signal |
| `rtl_reset_domains` | Reset domain analysis — reset signal source and sync/async reset classification |
| `rtl_always_classify` | Always block classification — sequential/combinational/latch judgment |
| `rtl_cross_domain_signals` | Cross-clock domain signal detection — CDC risk signal identification |
| `rtl_clock_tree` | Clock tree structure diagram — clock propagation path and frequency division hierarchy |
| `rtl_port_dataflow` | Port to internal signal data flow tracking |
| `rtl_sva_properties` | SVA assertion query — property/sequence/assert list |
### Elaboration (pyslang enhancement)
| Tool | Description |
|------|-------------|
| `rtl_elab_report` | Pyslang elaboration report — top module, generate expansion number, resolved signal number, diagnostic information |
| `rtl_elab_instances` | Elaborated instance list — include generate expansion complete hierarchy path |
| `rtl_resolved_signals` | Parameter evaluation signal list — original width vs resolved width comparison |
### Visualization
| Tool | Description |
|------|-------------|
| `rtl_visualize` | Unified visualization entrance, support 4 types of graphs |
**Graph Types:**
| Type | Description | Output |
|------|-------------|--------|
| `hierarchy` | Module hierarchy tree, double-click to drill down submodule, breadcrumb navigation | Mermaid / HTML |
| `fsm` | State transition graph (ellipse=state, edge=condition) | Mermaid / HTML |
| `dataflow` | Signal data flow tracking graph | Mermaid / HTML |
| `clock` | Clock domain structure graph (grouped by clock domain) | Mermaid / HTML |
| `auto` | Automatic detection target type | — |
HTML output uses vis.js interactive network graph, support zoom/drag/click details/hierarchy expansion.
## Architecture
```
verilog_mcp_server/
├── server.py # FastMCP application creation, CLI, stdio startup
├── config.yaml # Default configuration
│
├── indexer/ # tree-sitter parsing + data extraction
│ ├── builder.py # Full/incremental index construction (support parallel parsing)
│ ├── project_scanner.py # File discovery, .f file expansion (+incdir+/+define+ pass-through)
│ ├── verilog_parser.py # tree-sitter encapsulation
│ ├── module_extractor.py
│ ├── port_extractor.py # Port extraction (ANSI + non-ANSI)
│ ├── signal_extractor.py # Signal + testbench detection
│ ├── instance_extractor.py # Instantiation (including gate-level primitives + defparam)
│ ├── type_extractor.py
│ ├── package_extractor.py # Package definition + import declaration
│ ├── sva_extractor.py # SVA assertions
│ ├── macro_extractor.py # Macro definition
│ ├── function_task_extractor.py # Function/task extraction
│ ├── filelist_parser.py # .f file parsing (+incdir+/+define+/+libdir+)
│ ├── pyslang_parser.py # Pyslang compilation + elaboration
│ └── pyslang_extractor.py # Pyslang data extraction
│
├── database/ # SQLite + memory cache
│ ├── models.py # Data classes: ModuleDef, PortDef, SignalDef, PackageDef,
│ │ # FunctionDef, SvaDef, MacroDef, InstanceDef, etc.
│ ├── index_store.py # Index storage (module/type/package/function query)
│ ├── sqlite_backend.py # SQLite CRUD
│ └── errors.py
│
├── analysis/ # Analysis engine
│ ├── hierarchy.py # Module hierarchy tree (prefer pyslang data)
│ ├── fan_in.py # Signal fan-in tracking
│ ├── fan_out.py # Signal fan-out tracking
│ ├── fsm_detector.py # Finite state machine detection
│ ├── clock_analyzer.py # Clock domain analysis
│ ├── clock_tree.py # Clock domain hierarchy mapping
│ ├── always_classify.py # Always block classification
│ ├── cross_ref.py # Cross-reference
│ ├── expr_walker.py # Expression signal reference extraction
│ ├── signal_classifier.py
│ └── visualizer.py # Graph generation (Mermaid + vis.js HTML)
│
├── tools/ # MCP tool registration
│ ├── level1_search.py # Level 1 — query (including package/function search)
│ ├── level2_relation.py # Level 2 — relation analysis
│ ├── level3_analysis.py # Level 3 — intelligent analysis (including SVA query)
│ ├── visualize.py # Unified visualization
│ └── elab_tools.py # Pyslang elaboration report
│
├── templates/
│ └── visualizer.html # vis.js HTML template
│
└── scripts/
├── build-centos8.sh # CentOS 8.4 build script
└── tree_sitter_cache_hook.py # PyInstaller runtime hook
```
## Technology Stack
- **Parsing**: tree-sitter + pyslang (slang compiler frontend)
- tree-sitter: syntax-level parsing, extract source code structure
- pyslang: semantic-level elaboration, generate expansion, parameter evaluation, complete hierarchy tree
- Hierarchy construction prefer pyslang data, tree-sitter as fallback
- **Storage**: SQLite (WAL mode) + memory cache
- **Protocol**: MCP stdio (called by Claude Desktop / Claude Code)
- **Visualization**: Mermaid (text graph) + vis.js (interactive HTML)
- **Packaging**: PyInstaller standalone executable (CentOS 8.4 compatible)
- **Parallel**: `ProcessPoolExecutor` multi-process parsing (≥10 files automatically enabled)
## pyslang Integration
pyslang is the official Python binding of slang (the most complete open-source SystemVerilog compiler frontend).
### Configuration
```yaml
pyslang:
enabled: true
include_dirs: [] # include search path (automatically merge .f file's +incdir+)
defines: {} # Predefined macros (automatically merge .f file's +define+)
top_module: "" # Specify top module
```
### Capabilities
- **Generate expansion instance tracking**: `rtl_elab_instances` show genblk expansion complete hierarchy path
- **Parameter evaluation width**: `rtl_get_module` signal list show resolved width
- **Complete hierarchy tree**: `rtl_hierarchy` prefer pyslang data (including generate expansion)
- **Elaboration report**: `rtl_elab_report` show diagnostic information
### Degradation Handling
- When pyslang is not installed: automatically skip, tree-sitter index not affected
- When pyslang parsing fails: record warning, do not block index construction
- Incremental build: only trigger pyslang re-run when change involves parameter/generate/module interface
## Filelist Support
Support standard EDA `.f` file list format:
```bash
verilog-mcp-server --build -f project.f
```
`.f` file's `+incdir+` and `+define+` automatically pass to pyslang preprocessor:
```
# project.f
+incdir+./include
+incdir+./rtl
+define+SIM
+define+BUS_WIDTH=32
./rtl/top.sv
./rtl/cpu.sv
-f sub_module.f
```
## Run Test
```bash
pytest tests/ -v
```
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available