内容
# Quartus II MCP 服务器
一款 [模型上下文协议（MCP）](https://modelcontextprotocol.io) 服务器，为 **Claude** 提供对 **Intel/Altera Quartus II 13.1** 的完全访问权限 — 创建项目、编译设计、分配引脚、运行时序分析、通过 JTAG 编程 FPGA 等等，所有操作均可通过 Claude 对话完成。
---
## 您可以使用
连接后，您可以自然地与 Claude 交谈：
> _“创建一个名为 `blink` 的 Cyclone IV 项目，添加我的 `blink.v` 文件，将时钟分配给 PIN_R8，将 LED 分配给 PIN_A15，然后编译并编程我的 FPGA。”_
Claude 将调用相应的工具，并报告结果、错误和警告 — 无需手动点击 GUI。
---
## 需求
| 需求 | 版本 |
| ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
| [Quartus II](https://www.intel.com/content/www/us/en/software-kit/711791/intel-quartus-ii-web-edition-design-software-version-13-1-for-windows.html) | 13.1（Web 版或更高版本） |
| Python | 3.10 或更高版本 |
| [Claude 代码](https://claude.ai/download) | 最新版本 |
> **注意：** Quartus II 必须安装在运行 Claude Code 的同一台机器上。默认安装路径为 `C:\altera\13.1\`。如果您的安装路径不同，请参见 [配置](#配置)。
---
## 安装
### 1. 克隆此仓库
```bash
git clone https://github.com/irumvag/quartus_mcp_server.git
cd quartus-mcp-server
```
### 2. 安装 Python 依赖项
```bash
pip install mcp>=1.0.0
```
或使用需求文件：
```bash
pip install -r requirements.txt
```
### 3. 验证 Quartus 可访问性
打开终端并确认 Quartus shell 响应：
```
C:\altera\13.1\quartus\bin64\quartus_sh.exe --version
```
您应该看到类似 `Version 13.1.0 Build 162 ...` 的输出。
---
## 配置
### 选项 A — 项目级（推荐）
仓库中已包含 `.claude/settings.json`。打开它并 **更新路径** 以指向您机器上的 `quartus_mcp_server.py`：
```json
{
"mcpServers": {
"quartus": {
"command": "python",
"args": ["C:\\path\\to\\your\\quartus-mcp-server\\quartus_mcp_server.py"],
"env": {
"QUARTUS_ROOTDIR": "C:\\altera\\13.1\\quartus",
"QUARTUS_ROOTDIR_OVERRIDE": "C:\\altera\\13.1\\quartus"
}
}
}
}
```
> **如果 Quartus 安装在其他位置，** 也请更新 `QUARTUS_ROOTDIR` 和 `QUARTUS_ROOTDIR_OVERRIDE` 以匹配。
### 选项 B — 全局（在所有 Claude Code 会话中可用）
编辑（或创建）`C:\Users\YOUR_NAME\.claude\settings.json`：
```json
{
"mcpServers": {
"quartus": {
"command": "python",
"args": ["C:\\path\\to\\your\\quartus-mcp-server\\quartus_mcp_server.py"],
"env": {
"QUARTUS_ROOTDIR": "C:\\altera\\13.1\\quartus",
"QUARTUS_ROOTDIR_OVERRIDE": "C:\\altera\\13.1\\quartus"
}
}
}
}
```
### 如果 Quartus 不在 `C:\altera\13.1\`
打开 `quartus_mcp_server.py` 并更新第 22 行：
```python
QUARTUS_BIN = r"C:\altera\13.1\quartus\bin64" # ← 更改此项
```
### 激活
**重启 Claude Code.** 工具将以 `quartus__` 前缀出现（例如 `quartus__compile_project`）。
---
## 验证连接
重启 Claude Code 后，在该项目的目录中打开一个会话，并询问 Claude：
> _“列出可用的 Quartus 设备系列。”_
Claude 将调用 `get_device_families` 并返回一个列表，如 `Cyclone IV E`、`Stratix V` 等。如果成功，则表示一切正常。
---
## 可用工具（38 个）
### 项目管理
| 工具 | 描述 |
| ------------------ | ------------------------------------------------------ |
| `create_project` | 创建一个新项目（名称、目录、系列、设备） |
| `open_project` | 打开并验证现有项目 |
| `close_project` | 关闭当前项目 |
| `get_project_info` | 读取系列、设备、顶级实体 |
| `list_projects` | 在目录树中找到所有 `.qpf` 文件 |
| `archive_project` | 将项目存档到 `.qar` 文件 |
### 编译
| 工具 | 描述 |
| -------------------------- | ----------------------------------------------------------------- |
| `compile_project` | 运行完整或部分流程（`full` / `map` / `fit` / `asm` / `sta`） |
| `run_analysis_synthesis` | 运行分析和综合（`quartus_map`） |
| `run_fitter` | 运行适配器 / 放置和路由（`quartus_fit`） |
| `run_assembler` | 运行装配器 — 生成 `.sof` 和 `.pof` 文件 |
| `get_compilation_status` | 检查最后一次编译状态并列出输出工件 |
| `get_compilation_messages` | 从报告文件中提取错误和警告 |
### 时序分析
| 工具 | 描述 |
| --------------------- | ------------------------------------------ |
| `run_timing_analysis` | 运行静态时序分析（`quartus_sta`） |
| `get_timing_summary` | 读取 `.sta.summary` 报告 |
| `get_clock_summary` | 获取所有时钟名称和周期 |
| `get_timing_paths` | 获取两个节点之间的时序路径 |
### 引脚分配和设备
| 工具 | 描述 |
| ------------------------ | --------------------------------------------------------------- |
| `get_device_families` | 列出所有支持的设备系列 |
| `get_devices` | 列出一个系列的所有部件编号 |
| `get_pin_assignments` | 读取所有 `set_location_assignment` 条目 |
| `set_pin_assignment` | 将信号分配给引脚（+ 可选 I/O 标准） |
| `remove_pin_assignment` | 删除引脚位置分配 |
| `get_global_assignments` | 读取所有 `set_global_assignment` 条目 |
| `set_global_assignment` | 写入全局分配（例如 `SDC_FILE`、`TOP_LEVEL_ENTITY`） |
### JTAG / 编程器
| 工具 | 描述 |
| ----------------------- | ------------------------------------------------ |
| `detect_jtag_devices` | 检测 JTAG 连接的设备 |
| `get_programmer_cables` | 列出可用电缆（USB-Blaster 等） |
| `program_device` | 通过 JTAG 使用最新的 `.sof` 编程 FPGA |
### 报告和分析
| 工具 | 描述 |
| ----------------------- | --------------------------------------------- |
| `get_flow_summary` | 读取 `.flow.rpt` 编译摘要 |
| `get_resource_usage` | 获取 LUT/寄存器/内存利用率 |
| `get_power_report` | 运行 `quartus_pow` 并返回功率报告 |
| `run_design_rule_check` | 运行 `quartus_drc` |
### 文件管理
| 工具 | 描述 |
| -------------------------- | ---------------------------------------------------------- |
| `list_project_files` | 列出 `.qsf` 中注册的源文件 |
| `add_file_to_project` | 将文件添加到项目（`VERILOG_FILE`、`VHDL_FILE`、`SDC_FILE` 等） |
| `remove_file_from_project` | 从 `.qsf` 中删除文件 |
| `read_qsf` | 读取原始 `.qsf` 设置文件 |
### Tcl 脚本
| 工具 | 描述 |
| --------------------- | -------------------------------------------------- |
| `run_tcl_script` | 通过 `quartus_sh -t` 运行 `.tcl` 文件 |
| `execute_tcl_command` | 通过 `quartus_sh` 运行任意内联 Tcl 代码 |
---
## 示例对话
**创建和编译项目：**
```
您：创建一个 Cyclone IV E 项目，名为 "counter"，位于 C:\projects\counter，使用设备 EP4CE6E22C8
Claude：[调用 create_project] ✓ 项目已创建。
您：添加 C:\projects\counter\counter.v 到项目中
Claude：[调用 add_file_to_project] ✓ 文件已添加。
您：编译它
Claude：[调用 compile_project] ✓ 编译成功。0 个错误，3 个警告。
```
**编译后检查资源使用情况：**
```
您：我的设计使用了多少个逻辑单元？
Claude：[调用 get_resource_usage] → 42 / 6272 个逻辑单元（1%）
```
**从引脚表中分配引脚：**
```
您：将 clk 分配给 PIN_R8，reset 分配给 PIN_J15，led[0] 分配给 PIN_A15，I/O 标准为 3.3-V LVTTL
Claude：[调用 set_pin_assignment × 3] ✓ 所有引脚均已分配。
```
**编程 FPGA：**
```
您：通过 USB-Blaster 编程我的 FPGA
Claude：[调用 detect_jtag_devices，然后 program_device] ✓ 编程成功。
```
---
## 文件结构
```
quartus-mcp-server/
├── quartus_mcp_server.py # MCP 服务器 — 所有 38 个工具
├── requirements.txt # pip 依赖项（mcp>=1.0.0）
├── .claude/
│ └── settings.json # 将服务器注册到 Claude Code
└── README.md # 本文件
```
---
## 故障排除
**“找不到可执行文件”错误**
- 确认 Quartus 已安装，并且 `quartus_mcp_server.py` 中的 `QUARTUS_BIN` 指向您的 `bin64` 文件夹。
**“目录中未找到 .qpf 文件”**
- 将 `.qpf` 文件或包含它的目录的完整路径传递给相关工具。
**Claude Code 中未出现工具**
- 确保 `.claude/settings.json` 位于您在 Claude Code 中打开的项目目录中，**或** 您已更新全局 `~/.claude/settings.json`。
- 在更改任何设置后重启 Claude Code。
**编译挂起**
- 完整编译有 600 秒的超时限制。非常大的设计可能会超过此限制。在 `tool_compile_project` 中编辑 `timeout=600` 以增加超时限制。
**启动时出现 `mcp` 导入错误**
- 在 Claude Code 使用的相同 Python 环境中再次运行 `pip install mcp`。
---
## 许可证
MIT — 免费使用、修改和分发。
---
## 贡献
欢迎提交拉取请求。要添加新工具：
1. 在 `quartus_mcp_server.py` 中编写实现函数（`tool_your_name(...)`）
2. 在 `TOOLS` 列表中添加 `Tool(...)` 条目
3. 在 `TOOL_HANDLERS` 中添加调度条目
4. 更新此 README 中的表格
