This server provides a complete open-source FPGA toolchain accessible via MCP, enabling AI assistants to lint, simulate, synthesize, place-and-route, program, and manage IP cores — all from a chat interface.
HDL Quality & Formatting
Lint single or multi-file HDL projects (Verilog, SystemVerilog, VHDL) using iverilog, Verilator, GHDL, or Verible
Get structured per-line/per-column diagnostics
Auto-format HDL source using verible-verilog-format (Verilog/SV) or vsg (VHDL)
Design Flow
Simulate testbenches with Icarus Verilog or GHDL, returning PASS/FAIL verdicts and display output
Synthesize HDL using Yosys, targeting generic, iCE40, ECP5, Nexus, Gowin, Xilinx, or Intel families
Place-and-route with nextpnr, returning max frequency, critical path, resource utilization, and bitstream; supports board presets and constraint auto-detection
Program FPGAs via iceprog (iCE40) or openFPGALoader (ECP5/Gowin/Nexus)
IP Core Management
Browse and filter local IP cores; fetch core details and HDL source
Generate parameterized instantiation snippets
Search GitHub for open-source FPGA IP cores and import them into the local registry with FuseSoC CAPI2 support
Import local FuseSoC CAPI2 .core files
LiteX Integration
Build LiteX SoC gateware, generate SoCs without building, or run fully custom LiteX flows with arbitrary CLI arguments
Background Build Management
Start long-running builds in the background, poll status/progress, list all tracked builds, cancel running builds, and clean up old logs
Server & Registry Management
Check installed OSS CAD Suite tool versions and paths
Reload the IP core registry without restarting the server
List supported FPGA board presets
Provides synthesis capabilities targeting AMD (Xilinx) FPGA devices, allowing AI assistants to include AMD FPGAs in the design flow.
Enables searching and importing open-source FPGA IP cores from GitHub repositories into the local IP core registry.
Provides synthesis capabilities targeting Intel (Altera) FPGA devices, allowing AI assistants to include Intel FPGAs in the design flow.
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., "@fpgaZeroMCP Synthesize the Verilog in my project folder for the iCEBreaker board"
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.
An open-source Model Context Protocol server that gives AI assistants a complete FPGA toolchain — lint, simulate, synthesize, place-and-route, program the bitstream, and a live IP core registry backed by GitHub.
Ask your AI to search for cores, pull them in, lint HDL, synthesize a multi-file VHDL or Verilog project from disk, run a simulation, then flash the bitstream to your board — all without leaving your chat window.
Multi-language: Verilog, SystemVerilog, and VHDL (via ghdl-yosys-plugin)
Three input modes: inline code string, multi-file files dict, or project_dir path on disk
Filelist support: files.f/sources.f with +incdir+, +define+, and nested -f directives
Board presets: 11 built-in boards (iCEBreaker, ULX3S, TinyFPGA BX, Tang Nano, etc.) — sets target/device/package/clock automatically
Constraint auto-detection: finds .pcf/.lpf/.pdc/.cst in your project directory
Bitstream programming: flash via iceprog (iCE40) or openFPGALoader (ECP5/Gowin/Nexus/Xilinx)
Vivado: batch runs through start_build, Xilinx builds through LiteX, structured Vivado log parsing in build_status
Simulation verdict parsing: PASS/FAIL/UVM pattern detection with VCD signal summary
Background builds: long-running synthesis/PnR with status polling and a strict EDA-only command allowlist
Concurrent requests: ping, build status, and cancel are answered while a slow tool call is still running; notifications/cancelled aborts an in-flight call
Machine-readable results: structuredContent on tool results (MCP 2025-06-18) and a uniform error_code taxonomy for retry/fallback decisions
Progress notifications: notifications/progress at phase boundaries of synthesis, place-and-route, and LiteX runs when the client sends a progressToken
IP core registry: live search and import from GitHub with FuseSoC CAPI2 metadata
Health check: discover which OSS CAD Suite tools are installed and reachable
Related MCP server: vivado-mcp-agent
Your AI assistant <--> fpgaZeroMCP (stdio MCP server) <--> OSS tools
|
cores/ registry on GitHub
(uart_tx, fifo + any imported)The MCP server runs as a local subprocess. Your AI calls tools on it over JSON-RPC (stdio). The server shells out to Yosys, nextpnr, iverilog, Verilator, and others from OSS CAD Suite — and can pull open-source FPGA cores directly from GitHub.
Requirement | Notes |
Python 3.11+ | |
Bundles iverilog, Yosys, nextpnr, Verilator, Verible, GHDL in one download | |
Optional — only needed for LiteX tools |
Add OSS CAD Suite to your PATH after installing. All tool wrappers degrade gracefully if a tool is missing.
GitHub API requests are unauthenticated by default and subject to rate limits. Set a personal access token to increase limits:
# Linux/macOS
export GITHUB_TOKEN=ghp_...# Windows (PowerShell)
$env:GITHUB_TOKEN = "ghp_..."git clone https://github.com/lcapossio/fpgaZeroMCP
cd fpgaZeroMCP
pip install -e .Add to claude_desktop_config.json:
{
"mcpServers": {
"fpgaZeroMCP": {
"command": "python",
"args": ["/path/to/fpgaZeroMCP/server.py"],
"env": { "PYTHONPATH": "/path/to/fpgaZeroMCP" }
}
}
}Add to .vscode/mcp.json in your workspace:
{
"servers": {
"fpgaZeroMCP": {
"type": "stdio",
"command": "python",
"args": ["/path/to/fpgaZeroMCP/server.py"],
"env": { "PYTHONPATH": "/path/to/fpgaZeroMCP" }
}
}
}Add to your MCP settings (Settings → MCP Servers):
{
"fpgaZeroMCP": {
"command": "python",
"args": ["/path/to/fpgaZeroMCP/server.py"],
"env": { "PYTHONPATH": "/path/to/fpgaZeroMCP" }
}
}"Find me an I2C master core and import it."
"Synthesize the VHDL files in ~/projects/my_fpga and tell me the LUT count."
"PnR my project for the iCEBreaker board, then flash it."
"Run place-and-route with seed 42 to try for better timing."
"Lint this Verilog and fix any errors."
"Simulate this FIFO and tell me whether the testbench passed."
"Format this SystemVerilog file."
"Which OSS CAD Suite tools do I have installed?"
Tool | Description |
| Syntax/error check via iverilog (V/SV) or GHDL (VHDL) — single file |
| Lint multiple files together so cross-module references resolve |
| Structured per-line diagnostics — Verilator → verible fallback (V/SV), GHDL (VHDL) |
| Auto-format via verible-verilog-format (V/SV) or vsg (VHDL) |
Tool | Description |
| Compile and run testbenches — iverilog (V/SV) or GHDL (VHDL). Accepts |
| Yosys synthesis with resource stats. Accepts |
| Yosys + nextpnr in one step. Board presets, constraint auto-detection, bitstream written to disk ( |
| Flash a bitstream via |
| Enumerate built-in board presets (target/device/package/clock) |
Tool | Description |
| Browse the local registry, filter by category |
| Fetch manifest and HDL source for a core |
| Get a parameterized instantiation snippet + source files |
| Search GitHub for MIT-licensed FPGA IP repos |
| Download a GitHub repo into the local registry |
| Import a local FuseSoC CAPI2 |
Tool | Description |
| Run a LiteX board target with |
| Generate a LiteX SoC without building gateware |
| Run a LiteX board target with fully custom args |
Tool | Description |
| Start a long-running command in the background (allowlisted EDA tools only) |
| Check progress — status, elapsed time, parsed phase/utilization/timing |
| List all tracked builds (running and finished) |
| Kill a running background build |
| Delete old build logs by age and total size |
Tool | Description |
| Report which OSS CAD Suite tools are installed, with paths and versions |
| Re-scan core directories without restarting the server |
Cores live in cores/<name>/ — a core.json manifest and one or more HDL files. The server auto-discovers them on startup and reloads after any import.
Two reference cores are included (uart_tx, fifo) to demonstrate the format. The registry is not meant to grow here — it is powered by GitHub.
# Find a RISC-V softcore
search_github_cores("riscv softcore", language="verilog")
# Pull it in
import_github_core("YosysHQ/picorv32")
# It is now in the local registry
get_ip_core("picorv32")
generate_ip("picorv32", {"COMPRESSED_ISA": 1})The server automatically uses FuseSoC CAPI2 metadata (.core files) when found in the repo, giving richer parameter and port information. Only repos with an allowed license are accepted.
Do not open PRs adding cores to this repo. Instead:
Publish your HDL repo on GitHub with the fpga topic and an MIT license
Optionally add a FuseSoC CAPI2 .core file for richer metadata
Anyone can then import_github_core("you/your-core") directly
This keeps the server lean and lets the community grow organically on GitHub.
Target | Vendor / Family | Full OSS P&R |
| Lattice iCE40 | yes — nextpnr-ice40 |
| Lattice ECP5 | yes — nextpnr-ecp5 |
| Lattice Nexus (CrossLink-NX, CertusPro-NX) | yes — nextpnr-nexus |
| Gowin | yes — nextpnr-gowin |
| Xilinx / AMD | Synth only |
| Intel / Altera | Synth only |
| Technology-independent | Netlist only |
Common device/package values for place_and_route:
Target | device | package |
ice40 |
|
|
ecp5 |
|
|
nexus |
| (embedded in device string) |
gowin |
| (embedded in device string) |
LiteX is a Python SoC framework that can target many FPGA boards. fpgaZeroMCP exposes three dedicated LiteX tools and also accepts backend="litex" in synthesize and place_and_route.
# Dedicated tools
litex_build(board="arty", args=["--build"])
litex_soc(board="arty", args=["--no-compile"])
litex_flow(board="arty", args=["--build", "--output-dir", "build_arty"])
# As a backend in existing flow tools
synthesize(code="...", top_module="top", backend="litex", litex_board="arty")
place_and_route(code="...", top_module="top", target="ice40", device="hx1k",
backend="litex", litex_board="arty", litex_args=["--build"])You can point the registry at your own local HDL directories in two ways:
Environment variable:
Linux/macOS (colon-separated):
export USERCORES_PATH=/home/you/my-cores:/home/you/work-coresWindows (semicolon-separated, PowerShell):
$env:USERCORES_PATH = "C:\Users\you\my-cores;C:\Users\you\work-cores"Config file (~/.fpgazero_mcp/config.json):
{
"core_paths": [
"/home/you/my-cores",
"/home/you/work-cores"
]
}All paths are scanned on startup alongside the built-in cores/ directory.
By default, import_github_core accepts repos with any of these SPDX licenses:
MIT, BSD-2-Clause, BSD-3-Clause, Apache-2.0, ISC, GPL-2.0, GPL-3.0, LGPL-2.1, LGPL-3.0Override with the FPGAZERO_ALLOWED_LICENSES environment variable (comma-separated SPDX IDs):
# Linux/macOS
export FPGAZERO_ALLOWED_LICENSES=MIT
export FPGAZERO_ALLOWED_LICENSES=MIT,Apache-2.0# Windows (PowerShell)
$env:FPGAZERO_ALLOWED_LICENSES = "MIT"
$env:FPGAZERO_ALLOWED_LICENSES = "MIT,Apache-2.0"License IDs follow SPDX notation. The check is done at import time; search_github_cores returns results regardless of license so you can evaluate before importing.
pip install -e ".[dev]"
python -m pytest tests/ -vSome tests require OSS CAD Suite tools on PATH. Tests that need missing tools are skipped automatically.
The server runs as a 1-process-per-session subprocess under stdio transport (this is how MCP clients like Claude Desktop launch it). Each session takes ~60-90 MB RSS idle on Linux, mostly from the Python interpreter and dependencies.
If you run many concurrent MCP sessions, set these environment variables before launching your MCP client:
# Linux — reduces glibc malloc arena fragmentation (can save 10-20 MB per session)
export MALLOC_ARENA_MAX=2
# Strip bytecode position annotations from tracebacks (saves a few MB)
export PYTHONNODEBUGRANGES=1
# Skip .pyc cache files (no memory impact, avoids disk writes)
export PYTHONDONTWRITEBYTECODE=1These are zero-code changes and fully transparent.
Variable | Description |
| GitHub personal access token — raises API rate limits |
| Extra core search directories (OS path separator delimited) |
| Comma-separated SPDX IDs for |
| Override temporary workspace root directory |
| Root for persistent server artifacts — build logs, LiteX output, temp workspaces (default: |
| OS pathsep-separated list of extra directories that |
The Python API can be used directly without an MCP client:
from registry.resolver import CoreRegistry
from tools.lint import lint_hdl
reg = CoreRegistry()
# Import a core from GitHub
reg.import_github_core("ben-marshall/uart")
# Generate a parameterized instantiation
result = reg.generate_ip("uart", {"CLKS_PER_BIT": 868})
print(result["instantiation"])
# Lint some HDL
lint_hdl(open("my_design.v").read())python example.py # runs the built-in demo{
"name": "my_core",
"version": "1.0.0",
"description": "...",
"author": "you",
"license": "MIT",
"language": "verilog",
"category": "communication",
"tags": ["spi", "serial"],
"parameters": {
"DATA_WIDTH": { "type": "integer", "default": 8, "description": "..." }
},
"ports": {
"clk": { "direction": "input", "width": 1, "description": "System clock" }
},
"files": ["my_core.v"]
}Leonardo Capossio (bard0) — hello@bard0.com
MIT — see LICENSE.
Check the progress of a background build. Returns status (running/success/failed), elapsed time, and recent log output.
Inputs: build_id (required), tail_lines, parse.
Cancel a running background build.
Inputs: build_id (required).
Check which EDA tools are installed and reachable. Returns tool name, path, and version for each detected binary.
Inputs: no named parameters.
Delete old build logs to reclaim disk space. Removes logs older than max_age_days, then trims oldest until under max_total_mb.
Inputs: max_age_days, max_total_mb.
Format HDL source code and return the result. Verilog/SystemVerilog: uses verible-verilog-format. VHDL: uses vsg (pip install vsg). Returns the formatted code and whether it changed.
Inputs: code (required), language.
Generate a parameterized instance of an IP core. Returns the HDL source files and a ready-to-paste Verilog instantiation snippet with the requested parameter values applied.
Inputs: name (required), parameters, instance_name.
Return structured lint diagnostics (line, column, severity, message) for HDL source. Verilog/SystemVerilog: uses Verilator (primary) with verible-verilog-lint as fallback. VHDL: uses GHDL. All tools are part of OSS CAD Suite.
Inputs: code (required), language.
Fetch the full manifest and HDL source files for a named IP core.
Inputs: name (required).
Import a local FuseSoC CAPI2 .core file into the registry. HDL files referenced in the .core file must exist in the same directory. Useful when you already have FuseSoC cores checked out locally.
Inputs: path (required).
Download an open-source GitHub repository and add it to the local IP core registry. Automatically uses FuseSoC CAPI2 metadata (.core file) if one exists in the repo. After import, the core is immediately available via get_ip_core and generate_ip.
Inputs: repo (required), subdir, ref.
Lint HDL source code using iverilog/verilator (Verilog/SystemVerilog) or ghdl (VHDL). Use linter='verilator' to enable -Wall checks including multidriven net detection.
Inputs: code (required), language, top_module, linter.
Lint multiple HDL files together so cross-module references resolve. Pass a dict of filename-to-source pairs. All files are compiled in one invocation of iverilog/verilator (Verilog/SystemVerilog) or ghdl (VHDL). Use linter='verilator' to enable -Wall checks including multidriven net detection.
Inputs: files (required), language, top_module, timeout, +1 more.
List all known FPGA board presets with target, device, package, and clock frequency.
Inputs: no named parameters.
List all tracked builds (running and finished) with status summary.
Inputs: no named parameters.
List all available IP cores in the registry. Optionally filter by category.
Inputs: category.
Run LiteX board target with --build. Returns logs and output directory.
Inputs: board (required), args, output_dir, timeout.
Run a generic LiteX board target with caller-provided args.
Inputs: board (required), args, timeout.
Generate LiteX SoC without building gateware. Returns logs and output directory.
Inputs: board (required), args, output_dir, timeout.
Synthesize HDL with Yosys then place-and-route with nextpnr in one step. Provide source as: code (single string), files (dict of filename→source), or project_dir (path to HDL files on disk). If backend=litex, runs LiteX build and ignores HDL inputs. Returns max frequency, critical path, resource utilization, bitstream, and full logs. Supported targets: ice40, ecp5, nexus, gowin. Common device/package values: ice40: device=hx1k|hx8k|up5k|lp1k package=tq144|qn84|sg48|cm81 ecp5: device=25k|45k|85k package=CABGA256|CABGA381 nexus: device=LIFCL-40-9BG400C (package embedded in device string) gowin: device=GW1N-UV4LQ144C6/I5 (package embedded in device string)
Inputs: top_module (required), code, files, project_dir, +12 more.
Flash a bitstream to an FPGA board using iceprog (ice40) or openFPGALoader (ecp5/gowin/nexus). Provide bitstream as base64 (from place_and_route output) or a file path on disk.
Inputs: target (required), bitstream_b64, bitstream_path, programmer, +2 more.
Re-scan all core directories and rebuild the IP core cache. Call after adding cores to disk or editing config.json.
Inputs: no named parameters.
Search GitHub for open-source FPGA IP cores (MIT, BSD, Apache, GPL, etc). Returns repo names, star counts, descriptions and topics. Use import_github_core to download a result into the local registry.
Inputs: query (required), language, max_results.
Compile and simulate HDL using Icarus Verilog (iverilog + vvp) or GHDL (VHDL). Provide the design source and a separate testbench. Returns all $display/$monitor output (Verilog) or report output (VHDL) and any runtime errors.
Inputs: code (required), testbench (required), language, timeout.
Start a long-running build command in the background. Returns a build_id to check progress with build_status. Use for synthesis, place-and-route, LiteX builds, or any command that takes minutes.
Inputs: cmd (required), label, work_dir.
Synthesize HDL (Verilog, SystemVerilog, or VHDL) using Yosys or run LiteX backend. Provide source as: code (single string), files (dict of filename→source), or project_dir (path to HDL files on disk). Returns resource statistics and the list of inferred modules. Supported targets: generic, ice40, ecp5, gowin, xilinx, intel.
Inputs: top_module (required), code, files, project_dir, +6 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 25 tools
Each tool targets a distinct operation: build management, IP core management, HDL linting/simulation, synthesis/P&R, and LiteX flows. Overlaps like lint_hdl vs lint_project are clearly differentiated by single vs multi-file scope, so agents can reliably select the correct tool.
All tool names follow consistent snake_case with a verb_noun pattern (e.g., list_boards, generate_ip, cancel_build). No camelCase or mixed styles, making naming predictable and easy to remember.
25 tools cover a broad FPGA development workflow without being excessive. Each sub-domain (builds, IP cores, linting, synthesis, LiteX) is adequately represented, though the count is at the upper end of typical scopes.
The tool set covers the main FPGA flow: HDL linting, simulation, synthesis, place-and-route, and programming, plus build management and IP core discovery/import. Minor omissions like constraint file generation or waveform viewing exist, but core operations are well-supported.
A MCP server built for developers enabling Git based project management with project and personal…
Create, deploy, and operate MCP servers directly from your GitHub repositories.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
MCP Server for JFrog, providing tools for development and artifact management.