vivado-mcp

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

30 个精选 MCP 工具覆盖会话、综合、实现、时序、XDC、IP、波形与烧录；其余 Vivado 能力由通用 run_tcl 承载。相比把每条 Tcl 命令包装成工具，这种设计占用更少上下文，也更容易跨 Vivado 版本维护。

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

English: A lean MCP server for driving local Xilinx Vivado from AI agents. It provides 30 curated tools, 8 evidence-gated workflow prompts, GUI/headless/attach sessions, and raw Tcl escape hatches.

导航：快速开始 · 为什么是 30 个工具 · 工作流 Prompts · 工具列表 · 会话模式 · 架构 · 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 客户端

配置完成后重启客户端，即可加载 30 个工具、8 个工作流 Prompt 和 2 个会话状态 Resource。

6. 冒烟验证

在客户端中发送：

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

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

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

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

设计哲学 — 为什么是 30 个工具而不是 500 个？

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

• 每个工具都占用 AI 上下文（工具签名注入到每次系统提示）→ 调不调都烧 token
• 大模型比我们更会拼 Tcl（create_bd_cell 这种就是写一行 Tcl 的事）
• 绝大多数 facade 工具做的事 run_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
• 30 个精选工具 — 覆盖完整 FPGA 开发流程、智能诊断、离线解析和外部工具链联动
• 8 个证据驱动工作流 — 每个流程都要求新鲜基线、最小安全修改、复测门禁与明确停止条件
• 一条命令自检 — 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 时加载，不会全部常驻上下文。

会话模式

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）