vivado-mcp

让 Claude Code、Cursor、Codex 等 AI Agent 安全驱动本地 Xilinx Vivado。

32 个 MCP 工具覆盖会话、综合、实现、时序、CDC、XDC、IP、波形与烧录。可保存结构化时序结果、比较两次测量、离线查询 VCD 中的未知值与握手事件；通用 Vivado 操作由 run_tcl 承载。

本项目控制的是你本机安装的 Vivado，不是云端综合服务。命令在当前用户权限下执行；工具说明和诊断建议以中文为主。

English: A local Vivado MCP server with 32 tools, structured timing evidence and baseline comparison, bounded offline VCD queries, 11 workflow prompts, and 5 reusable skills.

导航：快速开始 · 实际调试场景 · 工具设计 · 工作流 Prompts · 工具列表 · 调试指南与 Skills · CLI · 反馈

环境要求

• Python ≥ 3.10，Windows / Linux
• Xilinx Vivado：必须安装在运行 vivado-mcp 的本机
• MCP Python SDK 2.x：唯一直接运行时依赖，pip 会自动安装

快速开始

1. 安装

python -m pip install vivado-mcp

多 Python 环境下，请让 MCP 客户端使用同一个 Python 解释器；必要时把下方配置中的 python 换成该解释器的绝对路径。

2. 先运行环境诊断

vivado-mcp doctor

doctor 默认完全只读，检查 Vivado 路径、init Tcl 注入、9999 端口协议、Claude Code/Codex 配置，并给出精确的修复计划。CI 或 Agent 可使用结构化输出：

vivado-mcp doctor --json

3. 注入 Vivado（一次性）

vivado-mcp install

这会修改你 Vivado 的 Vivado_init.tcl，让以后启动 GUI 时自动开启 TCP server（绑定 install 指定的单一端口，默认 9999；被占即退出，不会滑动到其他端口）。原文件会备份，vivado-mcp uninstall 可恢复。

如果 Vivado 装在受保护目录（如 C:\Program Files\），用管理员身份运行命令即可。

也可以让 doctor 执行安全修复：

vivado-mcp doctor --fix --client all

--fix 才会写文件：复用幂等的 Vivado 注入，并在备份后原子更新选定客户端配置；不会删除第三方注入、终止占用端口的进程或自动升级软件。

4. 配置 MCP 客户端

doctor --fix 可自动配置 Claude Code 和 Codex。手动配置时，Claude Code 使用 ~/.claude.json，Cursor 使用项目级 .cursor/mcp.json 或用户级 ~/.cursor/mcp.json；两者都在 mcpServers 中加入：

"vivado": {
  "command": "python",
  "args": ["-m", "vivado_mcp"],
  "env": {
    "VIVADO_PATH": "D:/Xilinx/Vivado/2019.1/bin/vivado.bat"
  },
  "type": "stdio"
}

Codex 使用 ~/.codex/config.toml：

[mcp_servers.vivado]
command = "python"
args = ["-m", "vivado_mcp"]

[mcp_servers.vivado.env]
VIVADO_PATH = "D:/Xilinx/Vivado/2019.1/bin/vivado.bat"

将 VIVADO_PATH 替换为你的 Vivado 实际路径：

• Windows: "D:/Xilinx/Vivado/2019.1/bin/vivado.bat"
• Linux: "/opt/Xilinx/Vivado/<版本>/bin/vivado"
• 也可以不设置 VIVADO_PATH，将 Vivado bin 目录加入系统 PATH。

VIVADO_PATH 负责让 MCP server 找到 Vivado 可执行文件；上一步的 vivado-mcp install 负责给 GUI/attach 模式注入 TCP server。其他支持 stdio MCP 的客户端使用相同的 command、args 和 env，配置文件位置以客户端文档为准。

5. 重启 MCP 客户端

配置完成后重启客户端，即可加载 32 个工具、11 个工作流 Prompt 和 2 个会话状态 Resource。五个 Skills 已随 Python 包分发，可显式导出到自选目录；不会自动修改客户端配置。对应 Prompt 从同一正文读取。

6. 冒烟验证

在客户端中发送：

启动一个 GUI 会话，然后执行 Tcl: version -short

AI 应依次调用 start_session(mode="gui") 和 run_tcl("version -short")。成功时 Vivado GUI 会启动（已有注入服务则直接 attach），并返回版本号。失败时直接运行 vivado-mcp doctor，无需逐项猜配置。

若 MCP 启动 GUI 时出现“进程提前退出”或连接超时，先查看错误中列出的 Vivado 启动日志和 Launcher 日志。启动器的错误可能发生在 Vivado 日志创建之前，因此两份都需要检查。日志默认位于系统临时目录的 vivado-mcp/logs，可用 VIVADO_MCP_LOG_DIR 指定目录；成功后也可从 list_sessions 的 startup_log / launcher_log 字段找到路径。 这些文件会继续记录该 GUI 进程的输出，关闭会话后保留，便于后续诊断。

如果手动打开同一 Vivado 能正常工作，可先完成上述 install 注入，再手动启动 GUI，使用 start_session(mode="attach", port=9999) 连接；安装时使用自定义 端口的，填写该端口。attach 不会新建 GUI 或本次启动日志。提交问题时请附上 版本、手动启动对照结果和相关错误片段，单独一个退出码不足以确定原因。

git clone https://github.com/mapleleavessssssss-wq/vivado-mcp.git
cd vivado-mcp
pip install -e ".[dev]"

各版本的完整变更和迁移说明见 CHANGELOG。

实际调试场景

完整参数、可复制例子和 Skills 使用方法见 调试指南。波形查询当前支持 VCD；WDB/FST 请先使用相应工具导出 VCD。

工具设计

部分同类 Vivado MCP 采用数百个细粒度工具，其中许多只是单条 Tcl 的包装。问题是：

• 过多相似入口增加工具选择和维护成本；具体上下文开销取决于客户端如何发现、加载工具。
• 单条 Tcl 操作可直接由 run_tcl 或 safe_tcl 完成。
• 结构化分析、可靠的多步操作和离线数据处理值得提供专门入口。

本项目只保留真正有本地价值的工具——Tcl 做不了或做不好的事：

1. 结构化解析：IO / 时序报告 → JSON / 中文摘要（比原始表格省 token）
2. 本地知识库：CRITICAL WARNING 按 ID 分类 + 中文修复建议（Tcl 里写这个太难）
3. 跨命令协议：sentinel、会话管理、超时、比特流前置安全检查
4. 跨会话工具：compare_xci 纯 Python 对比两个 XCI 文件，不需要 Vivado

其他（BD / 仿真 / XSCT / 硬件调试 / IP 配置等）全部交给 run_tcl，让大模型自己拼 Tcl。

特性

• 三种会话模式：GUI 可视化、Tcl 无头运行，以及只连接现有 GUI 的 attach
• 32 个精选工具 — 覆盖 FPGA 开发流程、智能诊断、离线解析和外部工具链联动
• 11 个证据驱动工作流 — 每个流程都要求新鲜基线、最小安全修改、复测门禁与明确停止条件
• 一条命令自检 — doctor 只读定位环境问题，doctor --fix 才执行受限、可备份的修复
• 可靠的长任务协议 — 综合/实现支持 wait=False 立即返回 job id，再由 get_run_progress 查询
• 超时响应不串台 — 每个 session 保留在途响应所有权；旧响应完成前拒绝下一命令，不会把 FIRST 的结果交给 SECOND
• 智能诊断 — 综合/实现后自动提取 CRITICAL WARNING / ERROR 分类 + 中文修复建议（含 18+ 种已知 ID）
• IO 验证 — XDC 约束（支持 -dict 和传统两种语法）对比实际引脚分配，GT 端口不匹配标记为 CRITICAL
• IP 调试 — 查询 IP 所有 CONFIG.* 参数（含 GUI 隐藏参数）、纯 Python 对比两个 XCI 文件
• Bitstream 安全检查 — 生成比特流前自动检测 CRITICAL WARNING 并阻止（可 force 跳过）
• 结构化报告 — IO 和时序报告解析为 JSON，便于 AI 精确提取数值（不再有"假 PASS"陷阱）
• 安全转义 — safe_tcl 自动对路径/标识符做 Tcl list 转义，Windows 含空格/中文/$ 的路径也能用
• 多会话支持 — 默认复用端口 9999 的单个 GUI（不同 session_id 也 attach 同一台）；传 port=0 自动分配空闲端口启动独立实例；server 只绑单一端口，被占即退出不滑动

工作流 Prompts

Prompts 解决的是“按什么顺序做、什么证据才算完成”，不会增加工具数量。正文只在选择该 Prompt 时加载，不会全部常驻上下文。

五个可分发 Skill 与对应 Prompt 使用同一份正文。查看及导出：

vivado-mcp skills list
vivado-mcp skills export ./fpga-skills
vivado-mcp skills export ./fpga-skills --skill vivado-cdc-audit

将导出的目录按客户端支持的方式导入即可。导出不覆盖已有修改：内容相同则跳过，冲突则报错，可选新目录重新导出。无需安装 SynthPilot 或 oh-my-fpga。

会话模式

start_session 工具支持三种模式：

用户: 启动 GUI 会话
AI: [调用 start_session(mode="gui")]
    → 端口空 → spawn 新 Vivado;端口已有 → attach 到现有 GUI(0.3.19+)
    
用户: 我刚自己手动开了 Vivado GUI,直接接管
AI: [调用 list_sessions]   → 看到 <external@9999>(你手动开的)
    [调用 start_session(mode="gui")]   → 自动 attach,不会再开第二个 GUI

用户: 批处理跑 10 个项目
AI: [调用 start_session(mode="tcl")] → 无 GUI,跑得更快

长时间综合/实现可以启动后立即返回，不占住一次 MCP 调用：

run_synthesis(run_name="synth_1", session_id="default", wait=False)
→ 综合已异步启动。job_id: default:synth_1

get_run_progress(run_name="synth_1", session_id="default")
→ STATUS / PROGRESS / 当前 phase / log tail / 最后更新时间

job_id 是由 session_id:run_name 组成的任务回执；查询时将两部分分别传给 get_run_progress。默认 wait=True 保持原有“等待完成并自动诊断”的兼容行为。每个 session 的命令严格串行，不同 session 可并行。

Resources

• vivado://sessions：当前所有会话的结构化状态
• vivado://session/{session_id}/status：指定会话的状态、模式、端口与存活信息

工具列表

会话管理

Tcl 执行（核心）

设计流程

新手引导 & 工程摸底

诊断(独家差异化)

IP 调试

离线摸底（无需 Vivado 会话，纯 Python）

结构化报告

通用报告（power / drc / clock / methodology 等）请直接用 run_tcl("report_power -return_string")，无需包装。

波形显示(XSim)

波形数据查询（无需 Vivado 会话）

可选:Claude Code Hook 配置示例

注意:.claude/ 目录不随仓库 / PyPI 包分发,下面是一份可选的 hook 配置示例, 复制到你自己项目的 .claude/settings.json 即可启用。hook 里 import 的 vivado_mcp.analysis 模块随 pip install vivado-mcp 一起装好,无需额外脚本。 所有 hook 命令均为单行 python -c(分号串联)——Windows cmd 与 bash 下都能直接执行, 多行 python -c 在 cmd 下会 SyntaxError 静默失效,自行改写时请保持单行。

配好后 AI 不只会"被动应答",还能主动守门:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__vivado__generate_bitstream",
        "hooks": [
          {
            "type": "command",
            "statusMessage": "bitstream-guard",
            "command": "python -c \"import json; print(json.dumps({'hookSpecificOutput': {'hookEventName': 'PreToolUse', 'permissionDecision': 'ask', 'permissionDecisionReason': '烧板前确认已跑 check_bitstream_readiness 且结论为 READY(时序违例/未布线状态下生成的是无效比特流)'}}))\""
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "statusMessage": "xdc-lint",
            "command": "python -c \"import json,sys; sys.stderr.reconfigure(encoding='utf-8'); d=json.load(sys.stdin); fp=d.get('tool_input',{}).get('file_path') or d.get('tool_response',{}).get('filePath') or ''; fp.lower().endswith('.xdc') or sys.exit(0); from vivado_mcp.analysis.xdc_linter import lint_xdc_files, format_lint_report; r=lint_xdc_files([fp]); r.issues and (sys.stderr.write('[xdc-lint hook] '+format_lint_report(r)+chr(10)), sys.exit(2))\""
          },
          {
            "type": "command",
            "statusMessage": "verilog-lint",
            "command": "python -c \"import json,sys; sys.stderr.reconfigure(encoding='utf-8'); d=json.load(sys.stdin); fp=d.get('tool_input',{}).get('file_path') or d.get('tool_response',{}).get('filePath') or ''; fp.lower().endswith(('.v','.sv')) or sys.exit(0); from vivado_mcp.analysis.verilog_quick_check import quick_check_verilog, format_report; t=format_report(quick_check_verilog(fp)); t and (sys.stderr.write('[verilog-lint hook] '+t+chr(10)), sys.exit(2))\""
          },
          {
            "type": "command",
            "statusMessage": "iverilog-check",
            "command": "python -c \"import json,sys; sys.stderr.reconfigure(encoding='utf-8'); d=json.load(sys.stdin); fp=d.get('tool_input',{}).get('file_path') or d.get('tool_response',{}).get('filePath') or ''; fp.lower().endswith(('.v','.sv')) or sys.exit(0); from vivado_mcp.analysis.verilog_compile_check import compile_check, format_compile_report; r=compile_check([fp], tool='auto', timeout=15.0); r.tool_available or sys.exit(0); r.errors and (sys.stderr.write('[iverilog-check hook] '+format_compile_report(r)+chr(10)), sys.exit(2))\""
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "statusMessage": "session-guard",
            "command": "python -c \"import sys,glob; sys.stderr.reconfigure(encoding='utf-8'); pids=glob.glob('vivado_pid*.str'); pids and (sys.stderr.write('[session-guard] 发现未清理的 Vivado session 痕迹: '+', '.join(pids)+'。建议用 mcp__vivado__stop_session 清理,或手动删除 .str 文件。'+chr(10)), sys.exit(2))\""
          }
        ]
      }
    ]
  }
}

把片段写入你项目的 .claude/settings.json 后,Claude Code 打开该项目时会弹框:"检测到项目配置了 hook,是否信任?" — 选 Yes 即启用。

要禁用单个或全部:在 .claude/settings.local.json(个人本地文件,不进 git)写入 {"hooks": {}} 覆盖即可。

使用示例 — 一轮完整的调试闭环

下面是 Vivado 2019.1 的两组实机片段：Basys 3 工程用于演示 IO/DRC 修复，独立的 Kintex-7 PCIe XDMA 工程用于演示时序诊断。两组结果串起 get_critical_warnings → XDC 修复 → compare_with_last 验证 → 时序自动诊断 → 烧板的完整闭环。

起点:打开项目,立刻看 ERROR / CW 详情

用户: 打开 basys3_uart 工程看看为什么 impl 挂了
AI:  [start_session(mode="gui")]
     [run_tcl("open_project .../basys3_uart.xpr")]
     [get_critical_warnings(run_name="impl_1")]

     !! 发现 3 条 ERROR !!
     诊断概览: errors=3, critical_warnings=0, warnings=0

     --- [ERROR][DRC BIVC-1] IO_STANDARD_MISMATCH (1 条) ---
       首次出现: 第 165 行
       示例消息: Bank IO standard Vcc: Conflicting Vcc voltages in bank 14...
       建议: Bank 内 IOSTANDARD 不一致(同一 Bank 的端口用了不同电压,如 LVCMOS18 和 LVCMOS33)。
       修复: 在 XDC 给所有端口显式指定 IOSTANDARD,同 Bank 保持电平一致。

     --- [ERROR][Vivado_Tcl 4-23] DRC_FAILED (1 条) ---
       建议: DRC 失败导致 Placer 未运行。
       修复: 查看同一日志里前面的 [DRC xxx-N] 定位根因,常见是 BIVC-1/NSTD-1/UCIO-1。

     --- [ERROR][Common 17-39] STAGE_ABORT (1 条) ---
       建议: 前置阶段失败导致后续阶段未能启动。

诊断第一步就锁定根因:BIVC-1 在 Bank 14 有电压冲突,后两条 ERROR 都是连锁反应。

修 XDC + 再综合

用户: 按建议在 XDC 里给所有端口显式补 IOSTANDARD 再综合
AI:  [xdc_auto_fix(board="basys3", dry_run=false)]   # 0.3.3 一键补 IOSTANDARD
     [run_synthesis]
     [run_implementation]

验证真的修到了点 — compare_with_last 差分

用户: 确认一下修好了
AI:  [get_critical_warnings(run_name="impl_1", compare_with_last=True)]

     诊断概览: errors=0, critical_warnings=0, warnings=3

     === CW 差分报告(对比上次快照)===
     修复效果: 已消除 3 条 / 新出现 0 条 / 仍存在 0 条

     [-] 已消除(3):
       • [DRC BIVC-1] IO_STANDARD_MISMATCH
       • [Vivado_Tcl 4-23] DRC_FAILED
       • [Common 17-39] STAGE_ABORT

     结论: 修复生效,所有上次存在的问题均已消除。

不需要人工对比两份日志 —— 差分直接给结论:3 条 ERROR 都消了,修复生效。

时序违例?自动给 Tcl 修复命令(0.3.9 亮点)

换到一个 WNS 违例的大工程(PCIe XDMA):

用户: 时序没过,告诉我怎么改
AI:  [get_timing_report]

     === 时序摘要 === 状态: FAIL (时序违例)
       Setup  WNS = -9.247 ns  TNS = -495735.094 ns
              失败端点: 247261 / 247354
       Hold   WHS = +0.015 ns  THS = 0.000 ns

     --- 违例路径 Top 10 ---
       [1] SETUP slack -9.247 ns  [HIGH_FANOUT]
           起点: .../xdma_0/.../tready_thrtl_reg/C
           终点: .../pcie_7x_i/pcie_block_i/CFGPMTURNOFFOKN
           延迟分解: logic 0.309 ns  route 2.094 ns  skew -6.845 ns  levels=2
           建议: 布线延迟(2.094 ns)远大于逻辑延迟(0.309 ns),通常是高扇出或跨芯片走线。
                 先跑 `report_high_fanout_nets -fanout_greater_than 1000` 定位,
                 然后对主干寄存器加 `set_property MAX_FANOUT 50 [get_cells <...>]`,
                 或在综合阶段加 `-fanout_limit 50` 让工具自动复制寄存器。

       [2] SETUP slack -9.219 ns  [HIGH_FANOUT]
           ...

不再有"时序挂了,咋办"的空转 —— 工具直接按模式(CDC / HIGH_FANOUT / LONG_COMBO / IO_UNREGISTERED / UNKNOWN)分类,给出具体 Tcl 命令。

烧板前安全门 + 编程设备

用户: 修好后准备烧板
AI:  [check_bitstream_readiness]
     核对目标实现 run、当前打开设计阶段、setup/hold/pulse-width 和 CW 查询是否完整。
     只有证据完整且不存在阻塞项才继续；CW=8 时不能当成 READY。

     [generate_bitstream]          # 先解决诊断问题，默认不跳过检查
     [program_device(bitstream_path="impl_1/top.bit")]  # 用户要求烧录且已确认设备时

常用旁路工具

其他单次查询/对比用例:

# 对比两个 XCI 找出配置漂移
compare_xci(file_a="golden.xci", file_b="suspect.xci")
# → PF0_DEVICE_ID: A=9024 | B=9038
# → LINK_SPEED:    A=5.0_GT/s | B=8.0_GT/s

# 验证 GT 引脚实际布局是否和 XDC 一致(支持 -dict 语法)
verify_io_placement_tool
# → !!! CRITICAL 不匹配 !!!  端口: pcie_7x_mgt_rtl_0_rxp[0]
#    XDC: AA4 | 实际: M6

# 任意 Tcl — AI 拼命令的主力
run_tcl("foreach p [get_ports] { puts \"$p: [get_property PACKAGE_PIN $p]\" }")
safe_tcl("set_property PACKAGE_PIN {0} [get_ports {1}]", args=["W5", "clk"])

架构

flowchart LR
    Agent["Claude Code / Cursor / Codex"] -->|"stdio MCP"| MCP["vivado-mcp"]
    MCP --> Tools["32 Tools"]
    MCP --> Prompts["11 Workflow Prompts"]
    MCP --> Resources["2 Session Resources"]
    Tools --> Tcl["SubprocessSession\nmode=tcl"]
    Tools --> Gui["GuiSession\nmode=gui"]
    Tools --> Attach["GuiSession\nmode=attach"]
    Tcl -->|"stdio + UUID sentinel"| VivadoTcl["vivado -mode tcl"]
    Gui -->|"TCP length-prefix"| VivadoGui["local Vivado GUI"]
    Attach -->|"TCP length-prefix"| VivadoGui

核心协议：

• subprocess 模式：catch + UUID sentinel（stdio 分帧，修复了 0.1.0 的行顺序 bug）
• GUI/attach 模式：TCP length-prefix framing（4 字节 BE + UTF-8 payload）
• 命令通过十六进制编码传输，避免 Tcl 注入，并覆盖含空格、中文和特殊字符的路径
• 每个 session 同时只拥有一个在途响应；调用超时不会释放协议所有权，避免迟到响应污染下一条命令

CLI 参考

开发

git clone https://github.com/mapleleavessssssss-wq/vivado-mcp.git
cd vivado-mcp
python -m pip install -e ".[dev]"

# 运行测试（不需要 Vivado）
pytest

# 代码检查
ruff check src/ tests/

反馈与 Bug 提交

通过 Code Agent 提交 Bug

遇到问题?把下面的 prompt 复制到你的 agent(Claude Code、Cursor、Codex 等)中,它会自动收集环境信息并创建规范的 issue:

我在使用 vivado-mcp (https://github.com/mapleleavessssssss-wq/vivado-mcp) 时遇到了问题。

请帮我提交一个 GitHub issue,按以下步骤操作:

1. 收集我的环境信息:
   - 操作系统: 运行 `[System.Environment]::OSVersion.VersionString`(PowerShell)或 `systeminfo | findstr /B /C:"OS"`(cmd)
   - Python 版本: 运行 `python --version`
   - vivado-mcp 版本: 运行 `vivado-mcp version`(或 `pip show vivado-mcp`)
   - Vivado 版本: 运行 `vivado -version`(若 vivado 在 PATH 中);否则从我项目的 .xpr 文件里抓 Project 标签
   - 当前 Vivado 进程: PowerShell 跑 `Get-Process | Where-Object { $_.ProcessName -like "*vivado*" }`
   - MCP 客户端类型(Claude Code / Cursor / Codex 等)及版本
   - 我使用的 Vivado 模式(`gui` / `tcl` / `attach`)

2. 询问我:
   - 期望的行为是什么
   - 实际发生了什么
   - 复现步骤(从 `start_session` 开始的完整工具调用序列)
   - 相关的工具输出 / 错误日志(优先 `get_critical_warnings` 或 `get_run_progress` 的输出)

3. 使用 `gh issue create` 在 GitHub 上创建 issue,格式如下:
   - 标题: 简洁的问题概述,前缀建议 `[bug]` / `[feature]` / `[docs]`
   - 正文包含以下部分: **环境信息**、**问题描述**、**复现步骤**、**期望行为 vs 实际行为**、**相关日志**
   - 如果是 bug 请添加 `bug` 标签;如果涉及特定工具(如 `get_critical_warnings`),在标题里点出来

仓库: mapleleavessssssss-wq/vivado-mcp

直接提 issue

也可以直接到 GitHub Issues 提交 —— 麻烦带上 vivado-mcp version、Vivado 版本、复现步骤。

文档

• CHANGELOG — 版本变更历史
• 迁移指南 0.1 → 0.2 — 每个被删工具的 run_tcl/safe_tcl 替代
• 审计报告 — 0.1.0 的 7 个 bug 根因分析
• IP 调试实践手册 — PCIe GT 映射调试、XCI 配置对比等实战
• 调试指南 — 时序对比、VCD 查询、Skills 与波形显示

许可证

Apache License 2.0