fpgaZeroMCP

オープンソースの Model Context Protocol サーバーです。AI アシスタントに完全な FPGA ツールチェーン（lint、シミュレーション、合成、配置配線、ビットストリームの書き込み、および GitHub をバックエンドにしたライブ IP コアレジストリ）を提供します。

AI にコアの検索、取り込み、HDL の lint、ディスク上の複数ファイルからなる VHDL/Verilog プロジェクトの合成、シミュレーションの実行、そしてボードへのビットストリームの書き込みまでを、チャットウィンドウから離れることなく実行させられます。

機能

• 多言語: Verilog、SystemVerilog、VHDL（ghdl-yosys-plugin 経由）

• 3 つの入力モード: インラインの code 文字列、複数ファイルの files dict、またはディスク上の project_dir パス

• ファイルリスト対応: files.f/sources.f と +incdir+、+define+、ネストされた -f ディレクティブ

• ボードプリセット: 11 の内蔵ボード（iCEBreaker、ULX3S、TinyFPGA BX、Tang Nano など）— target/device/package/clock を自動設定

• 制約ファイルの自動検出: プロジェクトディレクトリ内の .pcf/.lpf/.pdc/.cst を検出

• ビットストリーム書き込み: iceprog（iCE40）または openFPGALoader（ECP5/Gowin/Nexus/Xilinx）でフラッシュ

• Vivado: start_build によるバッチ実行、LiteX 経由の Xilinx ビルド、build_status での構造化された Vivado ログ解析

• シミュレーション判定の解析: PASS/FAIL/UVM パターン検出と VCD 信号サマリー

• バックグラウンドビルド: ステータスポーリング付きの長時間実行合成/配置配線と、EDA 専用コマンドのみを許可する厳格な許可リスト

• 並行リクエスト: 時間のかかるツール呼び出しが実行されている間も ping、ビルドステータス、キャンセルに応答します。notifications/cancelled は実行中の呼び出しを中止します

• 機械可読な結果: ツール結果の structuredContent（MCP 2025-06-18）と、リトライ/フォールバック判断のための統一 error_code 分類

• 進行通知: クライアントが progressToken を送信すると、合成、配置配線、LiteX 実行のフェーズ境界で notifications/progress を送信します

• IP コアレジストリ: FuseSoC CAPI2 メタデータによる GitHub からのライブ検索とインポート

• ヘルスチェック: インストール済みで到達可能な OSS CAD Suite ツールを検出します

Related MCP server: vivado-mcp-agent

目次

• 機能

• 仕組み

• 前提条件

• インストール

• MCP クライアントのセットアップ

• ツール

• IP コアレジストリ

• 合成ターゲット

• LiteX

• ローカルコアリポジトリ

• テスト

• 環境変数

• スタンドアロン / スクリプト

• core.json スキーマ

• ライセンス

仕組み

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

MCP サーバーはローカルのサブプロセスとして実行されます。AI は JSON-RPC（stdio）経由でサーバーのツールを呼び出します。サーバーは OSS CAD Suite の Yosys、nextpnr、iverilog、Verilator などのツールをシェル経由で実行し、オープンソースの FPGA コアを GitHub から直接取得することもできます。

前提条件

インストール後、OSS CAD Suite を PATH に追加してください。すべてのツールラッパーは、ツールが不足している場合でもグレースフルに動作します。

GitHub API アクセス

GitHub API リクエストは、デフォルトでは認証されておらず、レート制限の対象です。レート制限を引き上げるには、パーソナルアクセストークンを設定してください:

# Linux/macOS
export GITHUB_TOKEN=ghp_...

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

インストール

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

MCP クライアントのセットアップ

Claude Desktop

claude_desktop_config.json に追加:

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

VS Code (GitHub Copilot)

ワークスペース内の .vscode/mcp.json に追加:

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

Cursor / Windsurf

MCP 設定（Settings → MCP Servers）に追加:

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

プロンプト例

• "I2C マスターコアを探してインポートして。"

• "~/projects/my_fpga 内の VHDL ファイルを合成して、LUT 数を教えて。"

• "iCEBreaker ボード向けにプロジェクトを配置配線して、それからフラッシュして。"

• "より良いタイミングを試すために、シード 42 で配置配線を実行して。"

• "この Verilog を lint して、エラーを修正して。"

• "この FIFO をシミュレーションして、テストベンチがパスしたか教えて。"

• "この SystemVerilog ファイルをフォーマットして。"

• "どの OSS CAD Suite ツールがインストールされていますか？"

ツール

HDL 品質

設計フロー

IP コアレジストリ

LiteX

ビルド管理

サーバー / レジストリ

IP コアレジストリ

コアは cores/<name>/ に置かれます。— core.json マニフェストと 1 つ以上の HDL ファイルからなります。サーバーは起動時にそれらを自動検出し、インポート後にも再読み込みします。

フォーマットの例として、2 つのリファレンスコア（uart_tx、fifo）が含まれています。このレジストリはここで拡張することを意図していません — 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})

サーバーは、リポジトリ内に FuseSoC CAPI2 メタデータ（.core ファイル）が見つかった場合、それを自動的に使用し、より豊富なパラメータおよびポート情報を提供します。許可されたライセンス を持つリポジトリのみが受け入れられます。

コアの提供

このリポジトリにコアを追加する PR は開かないでください。 代わりに、次のようにしてください:

1. GitHub で fpga トピックと MIT ライセンスを付けて HDL リポジトリを公開する

2. 任意で、よりリッチなメタデータのための FuseSoC CAPI2 .core ファイルを追加する

3. その後は誰でも import_github_core("you/your-core") を直接呼び出せます

これによりサーバーは軽量なまま保たれ、コミュニティは GitHub 上で有機的に成長できます。

合成ターゲット

place_and_route でよく使用する device/package の値:

LiteX

LiteX は、多くの FPGA ボードをターゲットにできる Python 製 SoC フレームワークです。fpgaZeroMCP は専用の LiteX ツールを 3 つ公開しており、synthesize と place_and_route で backend="litex" も受け付けます。

# 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"])

ローカルコアリポジトリ

レジストリを自分のローカル HDL ディレクトリに向けるには、2 つの方法があります:

環境変数:

Linux/macOS（コロン区切り）:

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

Windows（セミコロン区切り、PowerShell）:

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

設定ファイル（~/.fpgazero_mcp/config.json）:

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

すべてのパスは、起動時に組み込みの cores/ ディレクトリとともにスキャンされます。

許可されるライセンス

デフォルトでは、import_github_core は以下のいずれかの SPDX ライセンスを持つリポジトリを受け入れます：

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

FPGAZERO_ALLOWED_LICENSES 環境変数(カンマ区切りの SPDX ID)で上書きできます：

# 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"

ライセンス ID は SPDX 表記に従います。チェックはインポート時に行われ、search_github_cores はライセンスに関係なく結果を返すため、インポートする前に評価できます。

テスト

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

一部のテストでは、PATH に OSS CAD Suite ツールが必要です。不足しているツールを必要とするテストは自動的にスキップされます。

メモリ使用量の削減

サーバーは stdio トランスポート上で、セッションごとに 1 プロセスずつのサブプロセスとして実行されます(これは Claude Desktop などの MCP クライアントが起動する方法です)。Linux では、各セッションのアイドル時 RSS は ~60〜90 MB で、そのほとんどは Python インタープリターと依存関係によるものです。

多数の MCP セッションを同時に実行する場合は、MCP クライアントを起動する前に次の環境変数を設定してください：

# 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

これらはコード変更が一切不要で、完全に透過的です。

環境変数

スタンドアロン / スクリプティング

Python API は MCP クライアントなしで直接使用できます：

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 スキーマ

{
  "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 — LICENSE を参照してください。