by mapleleavessssssss-wq
Provides AI‑driven assistance for Xilinx Vivado FPGA development by automatically parsing reports, diagnosing critical warnings, and generating remediation Tcl commands.
Vivado Mcp Server is an AI‑enhanced helper that tightly integrates with Xilinx Vivado to streamline the FPGA design flow. It extracts IO, timing, and utilization reports, converts them to structured JSON, categorises critical warnings, and supplies Chinese‑language fix suggestions together with ready‑to‑run Tcl snippets.
pip install vivado-mcp
vivado-mcp install
(this patches Vivado_init.tcl and backs up the original file.){
"vivado": {
"command": "python",
"args": ["-m", "vivado_mcp"],
"env": {"VIVADO_PATH": "D:/Xilinx/Vivado/2024.1/bin/vivado.bat"},
"type": "stdio"
}
}
start_session(mode="gui"|"tcl"|"attach") and then call any of the 25 bundled tools such as run_synthesis, get_critical_warnings, get_timing_report, etc.get_timing_report) that classifies paths (CDC, HIGH_FANOUT, LONG_COMBO, IO_UNREGISTERED, UNKNOWN) and emits concrete Tcl fixes.get_critical_warnings(compare_with_last=True)) that shows eliminated, new, and persistent issues after each run.xdc_auto_fix) that adds missing IOSTANDARD and creates appropriate create_clock commands for common boards.verilog_compile_check) using iverilog/verilator, 50× faster than Vivado synthesis.get_ip_status) and pure‑Python XCI comparison (compare_xci).get_run_progress) for long synthesis/implementation runs.get_next_suggestion drives beginners through project creation, top‑module setting, synthesis, implementation, and programming steps.tcl mode enables automated synthesis, timing checks, and report generation without a GUI.verify_io_placement and xdc_lint catch mismatched GT pins or missing constraints before costly implementation runs.get_ip_status alerts when IP cores are outdated, and compare_xci helps audit configuration drift.Q: Do I need a full Vivado installation? A: Yes, the server spawns Vivado (GUI or TCL mode) and communicates via TCP. Only the Vivado binaries are required; the Python package adds the MCP layer.
Q: Can I run the server on a headless CI runner?
A: Use start_session(mode="tcl") which launches Vivado in TCL mode. All tools work identically; the UI‑based hooks are simply bypassed.
Q: How does the server avoid TCL injection attacks?
A: Commands are sent using a length‑prefixed binary protocol and the helper safe_tcl automatically escapes paths and identifiers.
Q: What if I already have a custom Vivado_init.tcl?
A: vivado-mcp install creates a backup (*_backup.tcl) and appends the necessary server start‑up lines. You can revert with vivado-mcp uninstall.
Q: Is the tool limited to Xilinx 7‑series? A: No. It works with any Vivado‑supported device family as long as the appropriate device files are available.
Q: How are critical‑warning suggestions generated? A: The package ships a curated knowledge base mapping 19 known warning IDs to Chinese remediation scripts; unknown IDs are still categorised by severity.
精简的 MCP (Model Context Protocol) Server,通过 25 个工具 + 5 个智能 Hook 控制 Xilinx Vivado EDA——少即是多。
0.3 系列新增了什么:
- 时序违例自动定位(0.3.9):
get_timing_report违例时自动跑report_timing -max_paths 10,嗅探 5 种模式(CDC / HIGH_FANOUT / LONG_COMBO / IO_UNREGISTERED / UNKNOWN)并给出具体 Tcl 修复命令,不再让你对着时序日志发呆- CW 修复效果可视化(0.3.9):
get_critical_warnings(compare_with_last=True)对比上次快照,报告"已消除 N 条 / 新出现 N 条 / 仍存在 N 条",让"改 XDC 有没有改到点子上"直接有数- 长任务可视化:
get_run_progress让 10-30 分钟的综合/实现不再是黑盒- 新手引导:
get_next_suggestion根据项目状态告诉你下一步该干啥- XDC 一键自修:
xdc_auto_fix自动补 IOSTANDARD 和 create_clock period- 外部 Verilog 预检:
verilog_compile_check用 iverilog/verilator,比 Vivado 综合快 50 倍- IP 老化检测:
get_ip_status扫出项目里哪些 IP 需要升级- Commit 摘要:
get_pre_commit_summary生成 WNS/资源/CW 的 markdown 片段直接贴 commit body详见 CHANGELOG。
主流 Vivado MCP(如 SynthPilot)动辄 500+ 工具,每个工具本质是一行 Tcl 包装。问题是:
create_bd_cell 这种就是写一行 Tcl 的事)run_tcl("...") 能做本项目只保留真正有本地价值的工具——Tcl 做不了或做不好的事:
compare_xci 纯 Python 对比两个 XCI 文件,不需要 Vivado其他(BD / 仿真 / XSCT / 硬件调试 / IP 配置等)全部交给 run_tcl,让大模型自己拼 Tcl。
safe_tcl 自动对路径/标识符做 Tcl list 转义,Windows 含空格/中文/$ 的路径也能用mcp SDKpip install vivado-mcp
vivado-mcp install
这会修改你 Vivado 的 Vivado_init.tcl,让以后启动 GUI 时自动开启 TCP server(端口 9999-10003)。原文件会备份,vivado-mcp uninstall 可恢复。
如果 Vivado 装在受保护目录(如 C:\Program Files\),用管理员身份运行命令即可。
将以下内容复制到 ~/.claude.json 的 mcpServers 字段中:
"vivado": {
"command": "python",
"args": ["-m", "vivado_mcp"],
"env": {
"VIVADO_PATH": "D:/Xilinx/Vivado/2024.1/bin/vivado.bat"
},
"type": "stdio"
}
将
VIVADO_PATH替换为你的 Vivado 实际路径:
- Windows:
"D:/Xilinx/Vivado/2019.1/bin/vivado.bat"- Linux:
"/opt/Xilinx/Vivado/2024.1/bin/vivado"- 也可以不设置
VIVADO_PATH,将 Vivadobin目录加入系统PATH。
配置完成后重启 Claude Code,即可使用 25 个 Vivado 工具。
git clone https://github.com/mapleleavessssssss-wq/vivado-mcp.git
cd vivado-mcp
pip install -e ".[dev]"
start_session 工具支持三种模式:
| mode | 效果 | 适合 |
|---|---|---|
"gui" (默认) |
MCP 自动 spawn vivado -mode gui,你能看到 Vivado 图标 |
交互开发、实时观察波形/原理图 |
"tcl" |
vivado -mode tcl 无头子进程 |
CI、批处理、不需要 GUI |
"attach" |
连接到你已手动打开的 Vivado GUI | 想在 GUI 里手动捣鼓 + AI 辅助 |
用户: 启动 GUI 会话
AI: [调用 start_session(mode="gui")] → 桌面弹出 Vivado 窗口
用户: 批处理跑 10 个项目
AI: [调用 start_session(mode="tcl")] → 无 GUI,跑得更快
| 工具 | 说明 |
|---|---|
start_session |
启动 Vivado 会话(gui/tcl/attach 三种模式) |
stop_session |
关闭指定会话(B13 修复:taskkill /T 递归杀进程树 + 清 vivado_pid*.str) |
list_sessions |
列出所有活跃会话 |
| 工具 | 说明 |
|---|---|
run_tcl |
执行任意 Vivado Tcl 命令——AI 拼命令的主力 |
safe_tcl |
带参数模板,自动 Tcl 转义,路径含空格/中文/$ 时使用 |
| 工具 | 说明 |
|---|---|
run_synthesis |
运行综合,Python 轮询不阻塞,完成后自动 open_run + 诊断 |
run_implementation |
运行实现(布局布线) |
get_run_progress |
0.3.2 查 run 实时进度:Phase 序列 + log 尾部 + mtime,log 超 2 分钟不更新自动提示可能卡住 |
generate_bitstream |
生成比特流(默认前置 CRITICAL WARNING 安全检查) |
program_device |
编程 FPGA 设备(封装 open_hw_manager → connect → program) |
| 工具 | 说明 |
|---|---|
get_next_suggestion |
0.3.2 11 档决策表:没项目 → open/create,没顶层 → set_property TOP,综合完成 → run_implementation...每档附可执行命令 |
get_project_info |
0.3.0 一次拿齐项目摸底:名称/part/顶层/源文件/XDC/IP/runs 状态 |
get_pre_commit_summary |
0.3.4 生成 markdown 工程摘要直接贴 commit body:项目/时序 WNS+WHS/资源/CW/READY-WARN-BLOCK 门禁 |
| 工具 | 说明 |
|---|---|
get_critical_warnings |
提取并按 ID 分类 CRITICAL WARNING + ERROR,含 19 种已知 ID 的中文修复建议。0.3.9 加 compare_with_last=True 参数:对比上次快照输出"已消除 / 新出现 / 仍存在" 差分,验证修改是否真修到点 |
check_bitstream_readiness |
0.3.0 烧板前一键 READY/WARN/BLOCK 综合判定 |
verify_io_placement |
对比 XDC 约束(-dict/传统两种语法)与实际 IO 布局,GT 不匹配标为 CRITICAL |
xdc_lint |
0.3.0 纯 Python 静态 XDC 检查(PIN_CONFLICT / 漏 IOSTANDARD / DUPLICATE_PORT / CLOCK_NO_PERIOD / 跨文件冲突),不需 Vivado |
xdc_auto_fix |
0.3.3 自动补 IOSTANDARD + create_clock -period,dry_run 预览 + 板卡 profile(basys3/nexys/arty/zybo/kc705),不碰 PIN_CONFLICT |
verilog_compile_check |
0.3.4 用 iverilog / verilator 做语法 + 连接性检查,比 Vivado 综合快 50 倍。未装返回 SKIP + 安装指引,支持 Windows+scoop 路径自动发现 |
| 工具 | 说明 |
|---|---|
inspect_ip_params |
查询 IP 实例所有 CONFIG.* 参数(含 GUI 隐藏项),支持关键词过滤 |
compare_xci |
纯 Python 对比两个 XCI 文件的参数差异(无需 Vivado 会话) |
get_ip_status |
0.3.4 检查哪些 IP 需要升级 / 被锁定 / 已最新,附 upgrade_ip 批量建议 |
| 工具 | 说明 |
|---|---|
get_io_report |
IO 引脚报告(JSON),自动判定 GT/GPIO 类型 |
get_timing_report |
时序报告,含 PASS/FAIL 判定、数据来源标注(post-synth 估算 vs post-route 最终)、关键路径详情。0.3.9 违例时自动附 Top N 违例路径 + 5 种模式分类(CDC/HIGH_FANOUT/LONG_COMBO/IO_UNREGISTERED/UNKNOWN)+ 具体 Tcl 修复命令 |
get_utilization_report |
0.3.0 结构化资源占用(LUT/FF/BRAM/DSP/IOB),> 90% 标 CRITICAL,70-90% 标 WARN |
通用报告(power / drc / clock / methodology / cdc 等)请直接用
run_tcl("report_power -return_string"),无需包装。
仓库的 .claude/settings.json 预置了 5 个 Claude Code hook,让 AI 不只会"被动应答",还能主动守门:
| Hook | 触发事件 | 作用 |
|---|---|---|
bitstream-guard |
AI 调 generate_bitstream 前 |
拦截并提醒先跑 check_bitstream_readiness,避免时序违例时烧出废比特流 |
xdc-lint |
保存任意 .xdc 文件后 |
纯 Python 静态检查:PIN_CONFLICT / 漏 IOSTANDARD / create_clock 缺 -period 等,无需等综合 |
verilog-lint |
保存任意 .v / .sv 文件后 |
零依赖预检:module 名匹配文件名 / endmodule 存在 / 括号配对 |
iverilog-check |
保存任意 .v / .sv 文件后 |
0.3.4 iverilog 或 verilator 语法+连接性检查,未装静默跳过,有 error 时阻断 |
session-guard |
Claude 停下时 | 扫 vivado_pid*.str 文件,提醒清理未关闭的 Vivado session |
首次打开本仓库时 Claude Code 会弹框:"检测到项目配置了 hook,是否信任?" — 选 Yes 即启用。
要禁用单个或全部:在 .claude/settings.local.json(个人本地文件,不进 git)写入 {"hooks": {}} 覆盖即可。
下面是实机(Vivado 2019.1 + basys3 + Kintex-7)跑出来的真实片段,串起 get_critical_warnings → XDC 修复 → compare_with_last 验证 → 时序自动诊断 → 烧板的完整闭环。
用户: 打开 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 里给所有端口显式补 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 都消了,修复生效。
换到一个 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]
结论: READY — route_design Complete / WNS +0.026 ns / CW=8 (GT_LOC 都是 IP 内部,可忽略)
[generate_bitstream] # 自动拦截:有 CW 会阻止,可 force=True 跳过
[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
# → !!! 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"])
AI Tool (Claude/Cursor/Codex) ──(stdio MCP)──▶ vivado-mcp
│
┌─────────────────────┼──────────────────────┐
│ │ │
▼ ▼ ▼
SubprocessSession GuiSession GuiSession
(mode="tcl") (mode="gui") (mode="attach")
│ │ │
vivado -mode tcl Popen + TCP:9999+ TCP:9999+ 连到
(子进程 stdio) auto-spawn GUI 已开的 Vivado GUI
核心协议:
catch + UUID sentinel(stdio 分帧,修复了 0.1.0 的行顺序 bug)| 命令 | 说明 |
|---|---|
python -m vivado_mcp |
启动 MCP server(供 AI 工具调用) |
vivado-mcp serve |
同上 |
vivado-mcp install [path] [--port 9999] |
注入 Vivado_init.tcl |
vivado-mcp uninstall [path] |
从 Vivado_init.tcl 移除 |
vivado-mcp version |
显示版本 |
git clone https://github.com/mapleleavessssssss-wq/vivado-mcp.git
cd vivado-mcp
pip install -e ".[dev]"
# 运行测试(不需要 Vivado)
pytest
# 代码检查
ruff check src/ tests/
遇到问题?把下面的 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
也可以直接到 GitHub Issues 提交 —— 麻烦带上 vivado-mcp version、Vivado 版本、复现步骤。
Please log in to share your review and rating for this MCP.
Explore related MCPs that share similar capabilities and solve comparable challenges
by modelcontextprotocol
A Model Context Protocol server for Git repository interaction and automation.
by zed-industries
A high‑performance, multiplayer code editor designed for speed and collaboration.
by modelcontextprotocol
Model Context Protocol Servers
by modelcontextprotocol
A Model Context Protocol server that provides time and timezone conversion capabilities.
by cline
An autonomous coding assistant that can create and edit files, execute terminal commands, and interact with a browser directly from your IDE, operating step‑by‑step with explicit user permission.
by upstash
Provides up-to-date, version‑specific library documentation and code examples directly inside LLM prompts, eliminating outdated information and hallucinated APIs.
by daytonaio
Provides a secure, elastic infrastructure that creates isolated sandboxes for running AI‑generated code with sub‑90 ms startup, unlimited persistence, and OCI/Docker compatibility.
by continuedev
Enables faster shipping of code by integrating continuous AI agents across IDEs, terminals, and CI pipelines, offering chat, edit, autocomplete, and customizable agent workflows.
by github
Connects AI tools directly to GitHub, enabling natural‑language interactions for repository browsing, issue and pull‑request management, CI/CD monitoring, code‑security analysis, and team collaboration.
{
"mcpServers": {
"vivado": {
"command": "python",
"args": [
"-m",
"vivado_mcp"
],
"env": {
"VIVADO_PATH": "D:/Xilinx/Vivado/2024.1/bin/vivado.bat"
}
}
}
}claude mcp add vivado python -m vivado_mcp