Vivado Red MCP

vivado-red-mcp — Vivado MCP サーバー、Red Pitaya エディション

Claude などの AI アシスタントから AMD/Xilinx Vivado を直接操作できる MCP サーバーです。プロジェクトの作成、ブロックデザインの構築、合成、実装、シミュレーション、タイミング／使用率レポートの確認、ビットストリームの生成を、Vivado GUI を開かずに実行できます。

Red Pitaya STEMlab 125-14（Zynq xc7z010clg400-1）を第一級でサポートしています。純粋な RTL、または公式の RedPitaya-FPGA PS+PL（ARM + FPGA）バックボーンを使用して、自然言語による説明からボード上で動作する .bit.bin まで作成し、SSH 経由でデプロイできます。

coreyhahn/vivado_mcp からフォークし、大幅に拡張しました（93 個のツール）。ブロックデザイン／IP Integrator、IP カタログ、Hardware Manager、高度なレポート、Red Pitaya の RTL および PS+PL フロー、SSH デプロイに対応しています。

現在のバージョン：0.5.0 — 新機能とCHANGELOG.mdをご覧ください。

無関係な PyPI 上の vivado-mcp パッケージとは異なります。このプロジェクトは vivado-red-mcp で、Python モジュールは vivado_red_mcp、コマンドは vivado-red-mcp です。

---

目次

• できること
• テスト済み環境
• 要件
• インストール
• 最初の手順
• Red Pitaya
• 0.5.0 の新機能
• トラブルシューティング
• 利用可能なツール
• アーキテクチャ
• ライセンス

できること

• Vivado セッションの維持 — Tcl モードの Vivado プロセスを 1 つ起動したままにするため、コマンドのたびに 20～30 秒かかる起動時間が発生しません。
• プロジェクトと設計フロー — プロジェクトの作成／オープン、HDL ファイルと XDC ファイルの追加、合成、実装、ビットストリーム生成、実行ストラテジーに対応します。
• ブロックデザイン（IP Integrator） — ポート、IP コア、RTL モジュールセル、ネット、PS7 プリセット、検証、ラッパー生成に対応します。
• レポート — タイミング（WNS/TNS/WHS/THS）、使用率、クロック、電力、DRC、メソドロジー、QoR を、未加工のテキストではなく解析済みの値として返します。
• シミュレーション（xsim） — ビヘイビアと合成後／実装後に対応し、信号値の読み取りやブレークポイントを利用できます。
• Red Pitaya — ワンショット RTL ビルド、公式 RedPitaya-FPGA リポジトリからの完全な PS+PL ビルド、バンドル済みのボード制約、.bit.bin 生成、SSH デプロイに対応します。
• 生 Tcl — ツールでカバーされていない操作は、Tcl として実行できます（複数行スクリプトに対応）。

テスト済み環境

	状態
Vivado 2026.1, Windows 11	0.4.0 でエンドツーエンドの動作を検証済み：セッション、RTL および PS+PL の Red Pitaya ビルド、レポート、ビヘイビアおよび合成後の xsim、ブロックデザイン、RedPitaya-FPGA チュートリアル（下記参照）
Vivado 2020.1, Linux	当初の開発対象（0.3.x）。0.4.0 では再テストしていません
その他の Vivado リリース	動作する見込みです（汎用ツールは標準 Tcl を使用）。未テストです
Red Pitaya ボード	Red Pitaya の各フローでは STEMlab 125-14（Z10）のみ
Python	3.10 – 3.12
MCP Python SDK	1.x のみ（mcp>=1.0,<2、自動的に固定）

prj/Examples にある RedPitaya-FPGA のチュートリアル（Led_blink、Knight_rider、Stopwatch、Frequency_counter）は、サーバー経由でビットストリームまでビルドできます。Led_blink と Knight_rider は MCP ツールのみを使用して最初から再ビルドすると、チュートリアル独自のスクリプトで生成したものとバイト単位で同一のビットストリームが生成されます。

要件

1. Python 3.10 以降
2. AMD Vivado（Red Pitaya xc7z010 には無償版で十分です）。 インストール時に必要なのは Vivado と、デバイスの SoCs → Zynq-7000 だけです。 Vitis Model Composer と DocNav は不要です。
3. Vivado のライセンスファイル — 2025.x／2026.x では無償版にも必要です。 ライセンスがないと Vivado は起動しません（a valid license was not found）。
   • Vivado License Manager を開きます（Windows では <Vivado>/bin/vlm.bat、Linux では vlm）。
   • Obtain License → AMD のサイトで Vivado Basic Tier License, Node Locked License にチェックを入れます（無償、有効期限なし）→ Generate Node-Locked License。
   • ホスト ID：ネットワークカードの MAC アドレス（View Host Information に表示されます）。ライセンスは使用するネットワークではなく、PC に紐付けられます。
   • 受け取った Xilinx.lic を Load License → Copy License で読み込みます。
4. サーバーから Vivado にアクセスできること。方法は次のいずれかです。
   • PATH に追加します（Linux：source <Vivado>/settings64.sh、Windows：<Vivado>\bin を PATH に追加）。
   • または、Claude にフルパスを伝えます。Claude はそのパスを start_session に渡します （例：C:\AMDDesignTools\2026.1\Vivado\bin\vivado.bat）。

pexpect（Linux／macOS）または pywinpty（Windows）は自動的にインストールされます。

インストール

1. コードを取得してインストールする

git clone https://github.com/sinemortal/vivado-red-mcp.git
cd vivado-red-mcp
python -m venv .venv
# Windows:      .venv\Scripts\activate
# Linux/macOS:  source .venv/bin/activate
pip install -e .

pip は MCP SDK を 1.x に固定します。mcp を 2.x にアップグレードしないでください。サーバーが起動しなくなります（'Server' object has no attribute 'list_tools'）。

2. Claude Code に登録する

すべてのプロジェクトで一度だけ実行します。

claude mcp add --transport stdio --scope user vivado -- vivado-red-mcp

Claude Code の起動時に vivado-red-mcp が PATH にない場合（仮想環境を使っている場合によくあります）は、代わりに venv の Python を指定します。

# Windows
claude mcp add --transport stdio --scope user vivado -- "C:\path\to\vivado-red-mcp\.venv\Scripts\python.exe" -m vivado_red_mcp
# Linux/macOS
claude mcp add --transport stdio --scope user vivado -- /path/to/vivado-red-mcp/.venv/bin/python -m vivado_red_mcp

または、プロジェクトのルートに .mcp.json を置いて、そのプロジェクトだけで共有できます。

{
  "mcpServers": {
    "vivado": {
      "type": "stdio",
      "command": "vivado-red-mcp"
    }
  }
}

claude mcp list で確認します。vivado が接続済みと表示されていれば問題ありません。

3. 任意：RedPitaya-FPGA の自動ダウンロードを無効にする

起動時、PS+PL フロー用の RedPitaya-FPGA リポジトリ（ソース ZIP）が作業ディレクトリにない場合、サーバーがダウンロードします。これを無効にするには、環境変数 VIVADO_MCP_NO_AUTOFETCH=1 を設定します。必要に応じて rp_fetch_repo ツールからダウンロードできます。

はじめに

次のように、普段の言葉で Claude に話しかけてください。

1. 「Vivado セッションを開始して」（Vivado が PATH にない場合は、パスも指定します）
2. 「C:/work/my_proj/my_proj.xpr にあるプロジェクトを開いて」
3. 「合成と実装を実行して、タイミングを満たしているか教えて」
4. 「リソース使用率を表示して」
5. 「ビットストリームを生成して」
6. 「Vivado セッションを停止して」

Claude がツールを選ぶため、ツール名を指定して呼び出す必要はありません。

Red Pitaya

ARM プロセッサーが必要かどうかに応じて、2 つのフローがあります。

フロー	ツール	用途
RTL のみ（PS7 なし）	create_redpitaya_project_rtl	125 MHz ADC クロックで動作するロジック：LED、カウンター、拡張コネクターの GPIO。1 回の呼び出しで、作成 → ソース追加 → XDC → 合成 → 実装 → ビットストリーム → .bit.bin まで実行します
PS + PL	rp_fetch_repo → rp_setup_workspace → rp_build_project	ARM、DDR、または AXI が必要な設計。RedPitaya-FPGA に同梱されている PS7 ブロックデザインを再利用するため、Zynq を手動で再構成する必要はありません

プロンプトの例：

Red Pitaya 用に、125 MHz ADC クロックを使って led_o[0] で 1 Hz の LED 点滅回路を作成し、 ビルドして .bit.bin を渡してください。

ボードに結果をロードするには、Claude に deploy_to_redpitaya を使用するよう依頼してください（SSH、 デフォルトの認証情報は root／root。OS 1.04 の xdevcfg と OS 2.00 の fpgautil に対応）。または、自分でコピーします。

scp led_blinker.bit.bin [email protected]:/tmp/
ssh [email protected] 'cat /tmp/led_blinker.bit.bin > /dev/xdevcfg'

PS+PL と RedPitaya-FPGA リポジトリ。 現在の上流 master は Vivado 2025.1 を対象としています。以前のチェックアウトは 2020.1 を対象としていました。どちらのレイアウトにも対応しています。 rp_setup_workspace はリポジトリを別のワークスペースにコピーし、そのコピーだけにパッチを適用するため、 インストール済みの Vivado でスクリプトを実行できます（エクスポートされたブロックデザイン／IP スクリプトは、それ以外のリリースでは実行を拒否します）。また、git チェックアウトも不要です。ダウンロードしたリポジトリが変更されることはありません。詳細： get_vivado_doc redpitaya_ps_pl_flow。

同梱のボードデータ（data/boards/）：

• red_pitaya_125_14_full.xdc — 完全なピン配置（ADC、DAC、LED、拡張 コネクター、XADC）。公式の red_pitaya_top と同じポート名 （adc_dat_i[ch][bit]、dac_dat_o、exp_p_io、…）を使用し、上流の sdc/red_pitaya.xdc とピン単位で照合済みです。
• red_pitaya_125_14_leds_min.xdc — Hello World 設計向けの 125 MHz 差動 ADC クロック + 8 個の LED。
• red_pitaya_125_14_info.json — パーツ番号とボードのメタデータ。

RedPitaya チュートリアル（prj/Examples）では異なるポート名 （adc_dat_a_i、adc_clk_p_i、…）と PS7 プリセット（cfg/red_pitaya.xml）が使われています。 これらを再ビルドする場合は、それぞれ独自の cfg/ ファイルを使用してください。

イタリア語のプロンプト例と、低レベルな手順を段階的に説明したフローについては、USAGE.md を参照してください。

0.5.0 の新機能

名称を vivado-red-mcp に変更しました（パッケージ、Python モジュール vivado_red_mcp、コマンド vivado-red-mcp）。これにより、PyPI 上の無関係な vivado-mcp パッケージとの競合がなくなりました。以前のバージョンをインストールしている場合は、再インストールし、新しいコマンドを使って Claude Code に再登録してください（インストールを参照）。

0.4.0

Vivado 2026.1 および現行の RedPitaya-FPGA リポジトリで動作します。

修正内容：

• MCP SDK 2.x でサーバーが起動しない問題 → SDK を 1.x に固定しました。
• Windows で Claude Code がサーバーを起動するとシミュレーションが動作しない（xsim: Spawn failed）問題 → 修正しました。
• run_tcl に渡した複数行の Tcl が Windows で気付かないうちに破損する問題 → 修正しました。
• get_timing_summary が常に空の値を返し、get_utilization が新しいレポートを正しく読み取れない問題 → どちらも現行の Vivado 出力を解析するようになりました。
• ビルド直後にレポートを取得すると、メッセージなしで失敗する（No open design）問題 → 最新の完了済み run を自動的に開くようになりました。
• get_synthesis_errors_parsed が常にエラー数 0 を返す問題 → 失敗した IP run を含め、run のログを読み取るようになりました。
• 最近の Vivado で launch_simulation のモードが拒否される問題 → 修正しました。
• generate_bitstream が 300 秒後にタイムアウトし、結果を確認しない問題 → 結果を検証し、.bit のパスを返すようになりました。
• ライセンスがない場合（または起動に失敗した場合）に、2 分後に汎用エラーを返すのではなく、Vivado 自身のメッセージを数秒で報告するようになりました。
• 同梱の red_pitaya_125_14_full.xdc に誤ったピンが 6 個あった（ADC チャンネル A の MSB と dac_dat_o[8..12]）問題 → 修正しました。
• 新しい RedPitaya-FPGA レイアウトで PS+PL フローが動作しない問題 → 両方のレイアウトに対応しました。

新しいツール：create_bd_port、add_module_to_bd、configure_bd_cell、 set_run_strategy。全ツールの一覧は CHANGELOG.md を参照してください。

トラブルシューティング

症状	原因／対処
start_session が valid license was not found で失敗する	Vivado 2025.x/2026.x では、無償版でもライセンスファイルが必要です。要件を参照してください
start_session で Vivado が見つからない	<Vivado>/bin を PATH に追加するか、Claude に vivado.bat／vivado のフルパスを指定してください
サーバーが起動しない：'Server' object has no attribute 'list_tools'	MCP SDK 2.x がインストールされています。pip install "mcp>=1.0,<2" を実行してください
claude mcp list で vivado が失敗として表示される	Claude Code の PATH に vivado-red-mcp がありません。仮想環境の Python を使って登録してください（インストールを参照）
RedPitaya のサンプルで red_pitaya_pll ... port does not exist という合成エラーが発生する	このサーバーではなく、上流の prj/Examples/Simple_moving_average に関する問題です（rtl_250 が読み込まれます）
IP の実行中に Could not open 'C' for writing がまれに発生する	並列の Out-of-Context 実行に関する Vivado の断続的な問題です。合成を再実行してください
Windows でパスが長い	プロジェクトは短いパスに置いてください。Vivado と IP 生成では 260 文字の制限に達することがあります

利用可能なツール

セッション管理

• start_session - 永続的な Vivado Tcl セッションを開始します（vivado_path は任意）
• stop_session - Vivado セッションを停止します
• session_status - セッションの統計情報
• check_session_health - ハングまたは停止したセッションを検出し、必要に応じて復旧します
• get_host_status - ホストの CPU／メモリ状態

プロジェクト管理

• create_project - ディスク上にプロジェクトを作成します（デフォルトのパーツは xc7z010clg400-1）
• open_project ／ close_project - .xpr を開く、または閉じます
• get_project_info - パーツ、ディレクトリ、トップなど
• add_sources ／ add_constraints - HDL ファイルと XDC ファイルを追加します

設計フロー

• run_synthesis - 合成を実行します（実行ステータスを検証）
• run_implementation - 配置配線を実行します（実行ステータスを検証）
• generate_bitstream - ビットストリームを生成します（ステータスを検証し、.bit のパスを取得）
• set_run_strategy - 合成／実装の実行ストラテジーを設定します

レポートと解析

設計が開かれていない場合、レポートツールは最新の完了済み実行を自動的に開きます。

• get_timing_summary - WNS、TNS、WHS、THS、パルス幅、制約の達成／未達
• get_timing_paths - 違反パス／クリティカルパスの詳細なタイミングパス
• get_utilization - LUT、FF、BRAM、DSP、IO
• get_clocks - クロック情報
• get_messages - 合成／実装のメッセージ

設計クエリ

• get_design_hierarchy - モジュール／インスタンスの階層
• get_ports - トップレベルのポート
• get_nets ／ get_cells - ネットとセルを検索します

シミュレーション（xsim）

• set_simulation_top - テストベンチモジュールを設定します
• launch_simulation - ビヘイビア、合成後、または実装後のシミュレーション（機能／タイミング）
• run_simulation ／ step_simulation ／ restart_simulation ／ close_simulation
• get_simulation_time
• get_signal_value ／ get_signal_values - 信号を読み取ります
• get_simulation_objects ／ get_scopes - 階層を参照します
• add_signals_to_wave
• add_breakpoint ／ remove_breakpoints
• get_simulation_messages

ブロックデザイン（IP Integrator）— Zynq／AXI

• create_block_design - ブロックデザインを作成し、現在のデザインに設定します
• create_bd_port - スカラー、ベクター、またはインターフェースのポート
• add_ip_to_bd - CONFIG.* プロパティを指定して IP コア（VLNV）を追加します
• add_module_to_bd - RTL モジュールをモジュール参照セルとして追加します
• configure_bd_cell - 既存のセルに CONFIG.* を設定します（例：PS7 ボードプリセットのインポート）
• connect_bd_net ／ connect_bd_intf_net - ピン／ポートと AXI インターフェースを接続します
• auto_connect_axi - AXI マスター ↔ スレーブ向けの apply_bd_automation
• apply_ps7_preset - Zynq PS7 のオートメーション（FIXED_IO／DDR 外部接続）
• validate_block_design - BD DRC を実行します
• assign_bd_address - AXI アドレス範囲を自動割り当てします
• regenerate_bd_layout - レイアウトを整えます
• save_bd_design ／ close_bd_design - BD を保存または閉じます
• list_bd_cells - セルを一覧表示します
• generate_bd_wrapper - make_wrapper を実行し、ファイルセットに追加してトップに設定します

IP カタログ

• create_ip / configure_ip - カタログ IP を作成および設定します
• generate_ip_target / synth_ip - 生成物を出力し、アウトオブコンテキスト合成を実行します
• upgrade_ip / report_ip_status - IP バージョンをアップグレードおよび監査します

Hardware Manager（JTAG）

• open_hw_manager / close_hw_manager
• connect_hw_server - hw_server に接続します（デフォルトは localhost:3121）
• program_device - JTAG 経由で .bit をデバイスに書き込みます
• refresh_hw_device - JTAG チェーンを再読み込みします

高度なレポート

• report_power - 合計／動的／静的消費電力
• report_drc - DRC 違反を重大度別に分類します
• report_methodology - UltraFast 方法論のチェック
• report_qor_assessment - QoR スコア
• report_clock_interaction - クロック間パス
• generate_full_report / read_report_section - 全レポートをファイルに出力し、分割して読み込みます

Red Pitaya — RTL フロー

• list_boards / get_board_info - 同梱されているボードのメタデータと XDC パス（Vivado は不要）
• load_board_xdc - 同梱されているボード XDC をプロジェクトに追加します
• create_redpitaya_project_rtl - RTL ビルドを一括実行し、bit_path、 bin_path、解析済みの timing_summary および utilization を返します
• generate_cfgmem - /dev/xdevcfg / fpgautil 用に .bit を .bit.bin に変換します
• get_synthesis_errors_parsed - 失敗した IP の実行を含む、実行ログからの構造化されたエラー情報

Red Pitaya — PS+PL フロー

• rp_fetch_repo - RedPitaya-FPGA をダウンロードします（ソース zip。git は不要）
• rp_setup_workspace - ビルド用の、パッチ適用済みリポジトリの隔離されたコピーを用意します
• rp_list_projects - prj/* プロジェクトを一覧表示し、Z10 対応のものを示します
• rp_workspace_info - すでにビルド済みのプロジェクトを表示します
• rp_create_custom_project - 独自の PL ロジック用にベースプロジェクトを複製します
• rp_build_project - セットアップ → 合成 → 実装 → ビットストリーム → .bit.bin を実行し、タイミングを解析します

Red Pitaya — デプロイ（SSH、Vivado は不要）

• deploy_to_redpitaya - .bit.bin をアップロードして読み込みます（OS 1.04 では xdevcfg、OS 2.00 では fpgautil）
• ssh_redpitaya_exec - ボード上でシェルコマンドを実行します

ドキュメント（オフライン）

• list_vivado_docs / get_vivado_doc - 同梱されているトピック（block_design、 ps7_zynq、timing_constraints、synthesis_strategies、simulation_xsim、 red_pitaya_125_14、redpitaya_ps_pl_flow、tcl_quoting、hw_manager、 ip_integrator、pitfalls_2020_1）。各トピックには AMD ユーザーガイドへのリンクがあります

Tcl の直接実行とその他

• run_tcl - 任意の Tcl コマンドまたは複数行スクリプトを実行します
• run_tcl_script - .tcl ファイルを読み込みます
• request_feature / list_feature_requests

アーキテクチャ

┌─────────────────┐     MCP (JSON-RPC)     ┌─────────────────┐
│   Claude Code   │◄──────over stdio──────►│  vivado-red-mcp     │
│   (AI client)   │                        │  server         │
└─────────────────┘                        └────────┬────────┘
                                                    │ pexpect (Linux)
                                                    │ pywinpty/ConPTY (Windows)
                                                    ▼
                                           ┌─────────────────┐
                                           │ Vivado process  │
                                           │  (-mode tcl)    │
                                           └─────────────────┘

サーバーは Tcl モードで Vivado プロセスを 1 つ維持し、疑似端末経由で通信します。コマンドの完了は Vivado% プロンプトで確認します。各ツールファミリーは tools/ 以下の独自モジュールにあります。設計規約と既知の Vivado Tcl の落とし穴については、CLAUDE.md を参照してください。

コントリビューション

Issue とプルリクエストを歓迎します。CI には Vivado を使った自動テストはありません（各ツールにハンドラーがあることだけを確認します）。Vivado と連携するコードの変更は、実際の Vivado インストール環境で検証してください。

ライセンス

MIT — LICENSE を参照してください。同梱されているサードパーティの素材（Red Pitaya ボードの XDC ファイル、3-clause BSD）は THIRD-PARTY-NOTICES.md に記載されています。

謝辞

• coreyhahn/vivado_mcp（MIT）からフォークしました
• Red Pitaya のフローは RedPitaya/RedPitaya-FPGA を基盤としています
• Claude（Anthropic）を使用して開発しました
• Model Context Protocol を使用しています
• AMD Vivado と連携します