Vivado Red MCP

vivado-red-mcp — Vivado MCP 服务，Red Pitaya 版本

一个 MCP 服务，可让 Claude 等 AI 助手直接驱动 AMD/Xilinx Vivado：创建项目、构建块设计、综合、实现、仿真、读取时序/利用率报告并生成比特流，无需打开 Vivado GUI。

它原生支持 Red Pitaya STEMlab 125-14（Zynq xc7z010clg400-1）：你可以从自然语言描述出发，使用纯 RTL 或官方 RedPitaya-FPGA PS+PL（ARM + FPGA）骨干架构，在板卡上运行生成的 .bit.bin 文件，并通过 SSH 部署。

Fork 自 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 会话 — 一个 Vivado 进程以 Tcl 模式保持运行，命令无需每次都等待 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）构建为比特流。仅使用 MCP 工具从头重新构建的 Led_blink 和 Knight_rider，会生成与教程自带脚本逐字节完全相同的比特流。

要求

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 下）。许可证与电脑绑定，而非与你使用的网络绑定；
   • 使用 Load License → Copy License 加载收到的 Xilinx.lic。
4. 服务器能够访问 Vivado，可通过以下任一方式实现：
   • 将 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 中（虚拟 环境中很常见），请改为指向虚拟环境中的 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 自动下载

启动时，如果工作目录中缺少 RedPitaya-FPGA 仓库，服务会将其下载到工作目录中（源代码 zip），以供 PS+PL 工作流使用。设置 环境变量 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 处理器，有两种流程：

流程	工具	用途
仅 RTL（无 PS7）	create_redpitaya_project_rtl	由 125 MHz ADC 时钟驱动的逻辑：LED、计数器、扩展连接器 GPIO。一次调用即可完成 create → sources → XDC → synth → impl → bitstream → .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 — 125 MHz 差分 ADC 时钟 + 8 个 LED，适用于 hello-world 设计。
• 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。
• 通过 Claude Code 在 Windows 上启动服务时，仿真始终无法运行（xsim：Spawn failed）→ 已修复。
• 在 Windows 上通过 run_tcl 发送的多行 Tcl 会被静默破坏 → 已修复。
• get_timing_summary 始终返回空值；get_utilization 错误读取较新的报告 → 两者现在都能解析当前 Vivado 输出。
• 构建后立即生成报告会无提示失败（No open design）→ 现在会自动打开最新完成的运行。
• get_synthesis_errors_parsed 始终返回 0 个错误 → 现在会读取运行日志，包括失败的 IP 运行日志。
• launch_simulation 不接受新版 Vivado 支持的模式 → 已修复。
• generate_bitstream 在 300 秒后超时且不检查结果 → 现在会验证结果并返回 .bit 路径。
• 缺少许可证（或任何启动失败）时，现在会在几秒内报告 Vivado 自身的消息，而非在 2 分钟后返回通用错误。
• 内置的 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	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

Block design（IP Integrator）— Zynq / AXI

• create_block_design - 创建 Block Design 并将其设为当前设计
• create_bd_port - 标量、向量或接口端口
• add_ip_to_bd - 添加 IP 核（VLNV）并设置 CONFIG.* 属性
• 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 - 将 .bit 转换为 /dev/xdevcfg / fpgautil 使用的 .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 - 在板卡上运行 shell 命令

文档（离线）

• 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 进程，并使用 Vivado% 提示符判断命令何时执行完毕。 每类工具都位于 tools/ 下的独立模块中；有关设计约定和已知 Vivado Tcl 陷阱，请参阅 CLAUDE.md。

贡献

欢迎提交问题和拉取请求。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