fpgaZeroMCP

Ein Open-Source-Model Context Protocol-Server, der KI-Assistenten eine vollständige FPGA-Toolchain bietet — Linting, Simulation, Synthese, Place-and-Route, Bitstream-Programmierung und ein Live-Register für IP-Cores, das von GitHub gespeist wird.

Bitte deine KI, nach Cores zu suchen, sie herunterzuladen, HDL zu linten, ein Mehrdateien-VHDL- oder Verilog-Projekt von der Festplatte zu synthetisieren, eine Simulation auszuführen und anschließend den Bitstream auf dein Board zu flashen — einfach so, ohne dein Chatfenster zu verlassen.

Funktionen

• Mehrsprachig: Verilog, SystemVerilog und VHDL (via ghdl-yosys-plugin)

• Drei Eingabemodi: Inline-code-String, files-Dictionary mit mehreren Dateien oder project_dir-Pfad auf der Festplatte

• Filelist-Unterstützung: files.f/sources.f mit +incdir+, +define+ und verschachtelten -f-Direktiven

• Board-Presets: 11 integrierte Boards (iCEBreaker, ULX3S, TinyFPGA BX, Tang Nano usw.) — setzt Target/Device/Package/Clock automatisch

• Automatische Constraint-Erkennung: findet .pcf/.lpf/.pdc/.cst in deinem Projektverzeichnis

• Bitstream-Programmierung: Flashen via iceprog (iCE40) oder openFPGALoader (ECP5/Gowin/Nexus/Xilinx)

• Vivado: Stapel-Läufe über start_build, Xilinx-Builds über LiteX, strukturiertes Parsergebnis der Vivado-Logs in build_status

• Auswertung der Simulationsergebnisse: PASS/FAIL/UVM-Mustererkennung mit VCD-Signalzusammenfassung

• Hintergrund-Builds: langlaufende Synthese/PnR mit Statusabfrage und einer strikten Whitelist, die ausschließlich EDA-Befehle erlaubt

• Parallele Anfragen: ping, Build-Status und Abbrechen werden beantwortet, während ein langsamer Tool-Aufruf noch läuft; notifications/cancelled bricht einen in Bearbeitung befindlichen Aufruf ab

• Maschinenlesbare Ergebnisse: structuredContent bei den Tool-Ergebnissen (MCP 2025-06-18) und eine einheitliche error_code-Taxonomie für erneute Versuche und Fallback

• Fortschritts-Benachrichtigungen: notifications/progress an den Projektphasen-Übergängen von Synthese, Place-and-Route und LiteX-Läufen, wenn der Client ein progressToken sendet

• IP-Core-Registry: Live-Suche und Import aus GitHub mit FuseSoC-CAPI2-Metadaten

• Health-Check: erkennt, welche OSS-CAD-Suite-Werkzeuge installiert und erreichbar sind

Related MCP server: vivado-mcp-agent

Inhaltsverzeichnis

• Funktionen

• So funktioniert es

• Voraussetzungen

• Installation

• MCP-Client-Einrichtung

• Werkzeuge

• IP-Core-Registry

• Syntheseziele

• LiteX

• Lokale Core-Repositories

• Testen

• Umgebungsvariablen

• Standalone / Skripting

• core.json-Schema

• Lizenz

So funktioniert es

Der MCP-Server läuft als lokaler Subprozess. Deine KI ruft über JSON-RPC (stdio) dessen Tools auf. Der Server führt Yosys, nextpnr, iverilog, Verilator usw. aus der OSS CAD Suite aus — und kann Open-Source-FPGA-Cores direkt von GitHub holen.

Your AI assistant  <-->  fpgaZeroMCP (stdio MCP server)  <-->  OSS tools
                                    |
                           cores/   registry on GitHub
                           (uart_tx, fifo + any imported)

Voraussetzungen

Füge die OSS CAD Suite nach der Installation zu deinem PATH hinzu. Alle Tool-Wrapper reagieren sauber ab, wenn eines der Werkzeuge fehlt.

GitHub-API-Zugriff

GitHub-API-Anfragen sind standardmäßig nicht authentifiziert und unterliegen Rate Limits. Setze ein persönlichen Access-Token, um die Limits zu erhöhen:

# Linux/macOS
export GITHUB_TOKEN=ghp_...

# Windows (PowerShell)
$env:GITHUB_TOKEN = "ghp_..."

Installation

git clone https://github.com/lcapossio/fpgaZeroMCP
cd fpgaZeroMCP
pip install -e .

MCP-Client-Einrichtung

Claude Desktop

Füge dies zu claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "fpgaZeroMCP": {
      "command": "python",
      "args": ["/path/to/fpgaZeroMCP/server.py"],
      "env": { "PYTHONPATH": "/path/to/fpgaZeroMCP" }
    }
  }
}

VS Code (GitHub Copilot)

Füge dies in deiner Workspace in .vscode/mcp.json hinzu:

{
  "servers": {
    "fpgaZeroMCP": {
      "type": "stdio",
      "command": "python",
      "args": ["/path/to/fpgaZeroMCP/server.py"],
      "env": { "PYTHONPATH": "/path/to/fpgaZeroMCP" }
    }
  }
}

Cursor / Windsurf

Füge dies in deinen MCP-Einstellungen hinzu (Settings → MCP Servers):

{
  "fpgaZeroMCP": {
    "command": "python",
    "args": ["/path/to/fpgaZeroMCP/server.py"],
    "env": { "PYTHONPATH": "/path/to/fpgaZeroMCP" }
  }
}

Beispiel-Prompts

• „Such mir einen I2C-Master-Core und importiere ihn."

• „Synthetisiere die VHDL-Dateien in ~/projects/my_fpga und nenne mir die LUT-Anzahl."

• „Führe ein PnR für mein iCEBreaker-Board aus und flashe es danach."

• „Mach ein Place-and-Route mit Seed 42, um das Timing zu verbessern."

• „Linte dieses Verilog und behebe alle Fehler."

• „Simuliere dieses FIFO und sage mir, ob die Testbench bestanden hat."

• „Formatiere diese SystemVerilog-Datei."

• „Welche OSS-CAD-Suite-Werkzeuge habe ich installiert?"

Tools

HDL-Qualität

Design-Flow

IP-Core-Registry

LiteX

Build-Verwaltung

Server / Registry

IP-Core-Registry

Cores liegen in cores/<name>/ — einem core.json-Manifest und einer oder mehreren HDL-Dateien. Der Server erkennt sie automatisch beim Start und lädt die Registry nach jedem Import neu.

Zwei-Referenz-Cores sind enthalten (uart_tx, fifo), um das Format zu demonstrieren. Die Registry soll hier nicht wachsen — sie wird über GitHub gespeist.

Cores zur Laufzeit abrufen

# 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})

Der Server nutzt automatisch die FuseSoC-CAPI2-Metadaten (.core-Dateien), wenn sie im Repo vorhanden sind, und bietet so reichhaltigere Parameter- und Portinformationen. Akzeptiert werden nur Repos mit einer erlaubten Lizenz.

Einen Core beitragen

Eröffne keine PRs, die Cores zu diesem Repo hinzufügen. Stattdessen:

1. Veröffentliche dein HDL-Repo auf GitHub mit dem fpga-Topic und einer MIT-Lizenz

2. Füge optional eine FuseSoC-CAPI2-.core-Datei hinzu, für umfangreichere Metadaten

3. Danach kann jeder/jede direkt mit import_github_core("you/your-core") davon profitieren

So bleibt der Server schlank und die Community kann auf GitHub organisch wachsen.

Syntheseziele

Gängige device/package-Werte für place_and_route:

LiteX

LiteX ist ein Python-SoC-Framework, das viele FPGA-Boards unterstützt. fpgaZeroMCP stellt drei dedizierte LiteX-Tools bereit und akzeptiert sowie backend="litex" in synthesize und 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"])

Lokale Core-Repositories

Du kannst die Registry auf zwei Arten auf deine eigenen lokalen HDL-Verzeichnisse ausrichten:

Umgebungsvariable:

Linux/macOS (mit Doppelpunkt getrennt):

export USERCORES_PATH=/home/you/my-cores:/home/you/work-cores

Windows (mit Semikolon getrennt, PowerShell):

$env:USERCORES_PATH = "C:\Users\you\my-cores;C:\Users\you\work-cores"

Konfigurationsdatei (config.json):

{
  "core_paths": [
    "/home/you/my-cores",
    "/home/you/work-cores"
  ]
}

All paths are scanned on startup alongside the built-in cores/ directory.

Zulässige Lizenzen

Standardmäßig akzeptiert import_github_core Repos mit einer dieser SPDX-Lizenzen:

MIT, BSD-2-Clause, BSD-3-Clause, Apache-2.0, ISC, GPL-2.0, GPL-3.0, LGPL-2.1, LGPL-3.0

Überschreiben mit der Umgebungsvariable FPGAZERO_ALLOWED_LICENSES (kommagetrennte 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"

Lizenz-IDs folgen der SPDX-Notation. Die Prüfung erfolgt beim Import; search_github_cores liefert Ergebnisse unabhängig von der Lizenz, sodass Sie vor dem Import bewerten können.

Testen

pip install -e ".[dev]"
python -m pytest tests/ -v

Einige Tests benötigen OSS-CAD-Suite-Tools im PATH. Tests, die fehlende Tools benötigen, werden automatisch übersprungen.

Reduzierung des Speicherbedarfs

Der Server läuft als Subprozess mit einem Prozess pro Sitzung über den stdio-Transport (so starten ihn MCP-Clients wie Claude Desktop). Jede Sitzung belegt im Leerlauf auf Linux etwa 60-90 MB RSS, hauptsächlich durch Python-Interpreter und Abhängigkeiten.

Wenn Sie viele gleichzeitige MCP-Sitzungen ausführen, setzen Sie diese Umgebungsvariablen, bevor Sie Ihren MCP-Client starten:

# 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=1

Das sind Zero-Code-Änderungen und vollständig transparent.

Umgebungsvariablen

Standalone / Skripting

Die Python-API kann direkt ohne MCP-Client verwendet werden:

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

core.json-Schema

{
  "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"]
}

Autor

Leonardo Capossio (bard0) — hello@bard0.com

Lizenz

MIT — siehe LICENSE.