Vivado MCP
# Vivado MCP: AI로 Vivado 조작하기 (Windows 학생용)
AI(Claude Code, Codex, Gemini)에게 **말로 시키면 Vivado가 알아서 움직이게** 해 주는 도구입니다.
```
"lab3 프로젝트 열고 합성 돌려줘"
"타이밍 만족했어?"
"시뮬레이션 1us 돌리고 count 신호 값 알려줘"
```
> 아래 순서대로 **위에서부터 하나씩** 따라 하면 됩니다. 건너뛰지 마세요.
> 회색 상자 안의 명령어는 **복사해서 붙여넣기**만 하면 됩니다. 직접 타이핑하지 마세요.
---
## 한눈에 보기
| 단계 | 할 일 | 걸리는 시간 |
|------|-------|-------------|
| STEP 0 | PowerShell 여는 법 익히기 | 1분 |
| STEP 1 | 필요한 프로그램 설치 | 10~20분 |
| STEP 2 | 이 프로그램 다운로드 | 1분 |
| STEP 3 | `setup.bat` 더블클릭 | 2~3분 |
| STEP 4 | AI 켜서 확인 | 1분 |
**Vivado는 이미 설치되어 있다고 가정합니다.** (수업 시간에 설치한 그 Vivado)
---
## STEP 0. PowerShell 여는 법
앞으로 "PowerShell을 연다"는 말이 나오면 이렇게 하세요.
1. 키보드의 **Windows 키**를 누릅니다.
2. `powershell` 이라고 입력합니다.
3. **Windows PowerShell**이 나오면 **Enter**를 누릅니다.
4. 파란색 또는 검은색 창이 뜨면 성공입니다.
**명령어 붙여넣는 법:** 아래 회색 상자 오른쪽 위의 복사 버튼을 누르고, PowerShell 창에서 **마우스 오른쪽 클릭** (또는 `Ctrl + V`) 한 뒤 **Enter**.
**"창을 닫고 새로 연다"** 는 말이 나오면 PowerShell 창의 **X 버튼**으로 닫고, 위 1~3번을 다시 하면 됩니다.
---
## STEP 1. 필요한 프로그램 설치
### 1-1. PowerShell 스크립트 허용 (모두 필수, 처음 한 번만)
PowerShell을 열고 붙여넣기 → Enter:
```powershell
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned -Force
```
아무 메시지도 안 나오면 정상입니다.
### 1-2. Python, Git 설치 (모두 필수)
같은 창에 아래 **두 줄을 한 줄씩** 붙여넣고 Enter. 각각 끝날 때까지 기다리세요.
```powershell
winget install -e --id Python.Python.3.12 --override "/quiet InstallAllUsers=0 PrependPath=1" --accept-source-agreements --accept-package-agreements
```
```powershell
winget install -e --id Git.Git --accept-source-agreements --accept-package-agreements
```
> 중간에 "이 앱이 디바이스를 변경하도록 허용하시겠어요?" 창이 뜨면 **예**를 누르세요.
**PowerShell 창을 닫고 새로 연 뒤** 확인:
```powershell
python --version
```
`Python 3.12.x` 처럼 나오면 성공입니다.
### 1-3. AI 도구 설치 (셋 중 하나만 골라서)
어떤 걸 쓸지 모르겠으면 **수업에서 안내한 것**을 고르세요.
<details>
<summary><b>A. Claude Code를 쓸 경우 (클릭해서 펼치기)</b></summary>
PowerShell에 붙여넣기 → Enter:
```powershell
irm https://claude.ai/install.ps1 | iex
```
**창을 닫고 새로 연 뒤** 아래를 입력하고, 안내에 따라 로그인합니다.
```powershell
claude
```
로그인이 끝나면 `/exit` 를 입력해서 나옵니다.
</details>
<details>
<summary><b>B. Codex를 쓸 경우 (클릭해서 펼치기)</b></summary>
먼저 Node.js를 설치합니다.
```powershell
winget install -e --id OpenJS.NodeJS.LTS --accept-source-agreements --accept-package-agreements
```
**창을 닫고 새로 연 뒤:**
```powershell
npm install -g @openai/codex
```
설치가 끝나면 아래를 입력하고, **Sign in with ChatGPT**를 골라 로그인합니다.
```powershell
codex
```
로그인이 끝나면 `/quit` 를 입력해서 나옵니다.
> Codex **데스크톱 앱**을 쓰는 경우에도 이 설치 과정은 그대로 따라 하면 됩니다. (설정이 앱과 공유됩니다)
</details>
<details>
<summary><b>C. Gemini를 쓸 경우 (클릭해서 펼치기)</b></summary>
먼저 Node.js를 설치합니다.
```powershell
winget install -e --id OpenJS.NodeJS.LTS --accept-source-agreements --accept-package-agreements
```
**창을 닫고 새로 연 뒤:**
```powershell
npm install -g @google/gemini-cli
```
설치가 끝나면 아래를 입력하고, **Login with Google**을 골라 로그인합니다.
```powershell
gemini
```
로그인이 끝나면 `/quit` 를 입력해서 나옵니다.
</details>
---
## STEP 2. 이 프로그램 다운로드
PowerShell을 열고 아래를 **한 줄씩** 붙여넣기 → Enter:
```powershell
cd C:\
```
```powershell
git clone https://github.com/binghin2/Vivado_mcp_student.git vivado_mcp
```
이제 `C:\vivado_mcp` 폴더가 생겼습니다.
> **중요:** 이 폴더는 **지우거나 옮기지 마세요.** 지우면 AI가 Vivado를 못 씁니다.
---
## STEP 3. 설치 프로그램 실행
1. **파일 탐색기**를 엽니다. (`Windows 키 + E`)
2. 주소창에 `C:\vivado_mcp` 를 입력하고 Enter.
3. **`setup.bat`** 파일을 **더블클릭**합니다.
- "Windows의 PC 보호" 창이 뜨면 **추가 정보** → **실행**을 누르세요.
4. 검은 창에서 설치가 진행됩니다. **건드리지 말고 기다리세요.** (2~3분)
화면이 이렇게 나오면 성공입니다.
```
[1/6] Python 확인
[OK] Python 3.12
[2/6] Vivado 찾기
[OK] C:\AMDDesignTools\2026.1\Vivado\bin
[3/6] Vivado 를 PATH 에 등록
[OK] 등록 완료
[4/6] vivado_mcp 설치 (1~2분 걸릴 수 있습니다)
[OK] 설치 완료
[5/6] Vivado 실행 테스트 (30초~1분 걸릴 수 있습니다)
[OK] Vivado 가 정상적으로 실행됩니다.
[6/6] AI 도구에 등록 (Claude Code / Codex / Gemini)
[OK] Claude Code
[OK] Codex
[OK] Gemini
==============================================
설치 완료!
==============================================
```
- 설치하지 않은 AI 도구는 `[건너뜀]`으로 나와도 괜찮습니다.
- **`[실패]`가 보이면** 아래 [문제가 생겼을 때](#문제가-생겼을-때)를 보세요.
- **"Vivado 를 자동으로 찾지 못했습니다"** 가 나오면 [여기](#vivado-를-자동으로-찾지-못했습니다)를 보세요.
마지막에 `계속하려면 아무 키나 누르십시오...` 가 나오면 아무 키나 눌러 창을 닫습니다.
---
## STEP 4. AI 켜서 확인
**열려 있는 PowerShell 창을 전부 닫고**, 새 PowerShell을 엽니다.
먼저 작업용 폴더를 만들고 그 안으로 이동합니다. (한 줄씩 붙여넣기)
```powershell
mkdir C:\work -Force
```
```powershell
cd C:\work
```
> 앞으로 Vivado 프로젝트도 `C:\work` 안에 만들면 편합니다. (예: `C:\work\lab3`)
그다음 **내가 설치한 AI**를 실행합니다.
| 쓰는 AI | 입력할 명령 |
|---------|-------------|
| Claude Code | `claude` |
| Codex | `codex` |
| Gemini | `gemini` |
AI가 켜지면 `/mcp` 를 입력하고 Enter.
목록에 **vivado** 가 보이면 성공입니다.
이제 이렇게 입력해 보세요.
```
Vivado 세션 시작하고 버전 알려줘
```
> AI가 "이 도구를 실행해도 될까요?" 라고 물어보면 **허용 (Yes / Allow)** 을 고르세요.
> 매번 묻는 게 귀찮으면 "항상 허용 (Always allow / don't ask again)" 을 골라도 됩니다.
---
## 사용 예시
그냥 **한국어로 시키면 됩니다.** 복사해서 써 보세요.
```
Vivado 세션 시작해줘
```
```
C:\work\lab3\lab3.xpr 프로젝트 열어줘
```
```
합성 돌리고 끝나면 리소스 사용량 보여줘
```
```
구현까지 돌리고 타이밍 만족하는지 확인해줘
```
```
타이밍 위반 나는 경로 상위 5개 보여주고 원인 설명해줘
```
```
비트스트림 생성해줘
```
```
tb_counter 테스트벤치로 시뮬레이션 1us 돌리고 count 신호 값 알려줘
```
```
Vivado 세션 종료해줘
```
**꼭 알아둘 것**
- **처음에 "Vivado 세션 시작해줘"** 를 해야 합니다. Vivado가 켜지는 데 30초~1분 걸립니다.
- 합성, 구현은 오래 걸립니다. 중간에 **"진행 상황 알려줘"** 라고 물어보면 됩니다.
- **다 쓰면 "Vivado 세션 종료해줘"** 를 꼭 하세요. 안 하면 Vivado가 컴퓨터 메모리를 계속 차지합니다.
- 프로젝트 폴더 경로에 **한글이나 띄어쓰기가 없게** 하세요. (Vivado 자체 제약)
- 좋은 예: `C:\work\lab3`
- 나쁜 예: `C:\Users\홍길동\바탕 화면\실습 3`
---
## 문제가 생겼을 때
### `winget` 을(를) 인식할 수 없습니다
Microsoft Store를 열고 **앱 설치 관리자**를 검색해서 **업데이트**(또는 설치)하세요. 그다음 PowerShell을 새로 엽니다.
### `python` 을 입력했더니 Microsoft Store가 열려요
Python이 설치되지 않은 상태입니다. [1-2](#1-2-python-git-설치-모두-필수)를 다시 하고, **창을 닫고 새로 연 뒤** 확인하세요.
### "이 시스템에서 스크립트를 실행할 수 없으므로..." 라는 빨간 글씨
[1-1](#1-1-powershell-스크립트-허용-모두-필수-처음-한-번만)을 하지 않은 것입니다. 1-1을 하고 다시 시도하세요.
### `claude` / `codex` / `gemini` 을(를) 인식할 수 없습니다
설치 직후라면 **창을 닫고 새로 열어** 보세요. 그래도 안 되면 [1-3](#1-3-ai-도구-설치-셋-중-하나만-골라서)을 다시 하세요.
### Vivado 를 자동으로 찾지 못했습니다
Vivado가 기본 위치가 아닌 곳에 설치된 경우입니다.
1. 파일 탐색기에서 `vivado.bat` 파일을 찾습니다. (보통 `...\Vivado\2023.2\bin` 같은 폴더 안)
2. 그 폴더를 연 상태에서 **주소창을 클릭**하고 `Ctrl + C`로 경로를 복사합니다.
3. 설치 창의 `경로:` 부분에 마우스 오른쪽 클릭으로 붙여넣고 Enter.
### `/mcp` 에 vivado 가 안 보여요
1. PowerShell 창을 **전부** 닫고 새로 열어서 다시 해 보세요.
2. 그래도 안 되면 `C:\vivado_mcp\setup.bat` 을 **한 번 더** 더블클릭하세요.
3. AI 도구를 `setup.bat` **보다 나중에** 설치했다면 반드시 `setup.bat` 을 다시 실행해야 합니다.
### 그래도 안 돼요
`setup.bat` 실행 화면 전체를 **캡처**해서 조교/교수님께 보내 주세요.
---
## (참고) 수동 등록 방법
`setup.bat` 이 자동으로 해 주는 내용입니다. 보통은 볼 필요 없습니다.
<details>
<summary>펼치기</summary>
**Claude Code**
```powershell
claude mcp add --scope user vivado -- python -m vivado_mcp
```
**Codex** — `C:\Users\<내이름>\.codex\config.toml` 맨 아래에 추가:
```toml
[mcp_servers.vivado]
command = "python"
args = ["-m", "vivado_mcp"]
startup_timeout_sec = 60
tool_timeout_sec = 600
```
**Gemini 수동 등록** — `C:\Users\<내이름>\.gemini\settings.json` 에 `mcpServers` 항목 추가:
```json
{
"mcpServers": {
"vivado": {
"command": "python",
"args": ["-m", "vivado_mcp"],
"timeout": 600000
}
}
}
```
기존 내용이 있으면 지우지 말고 `mcpServers` 부분만 합쳐 넣으세요.
`setup.bat` 은 기존 설정 파일을 수정하기 전에 `.bak` 백업 파일을 만들어 둡니다.
</details>
---
## 삭제하기
PowerShell에서:
```powershell
claude mcp remove --scope user vivado
python -m pip uninstall -y vivado-mcp
```
그다음 `C:\vivado_mcp` 폴더를 지우면 됩니다.
(Codex/Gemini는 위 설정 파일에서 `vivado` 부분을 지우세요.)
---
## 사용 가능한 기능 (참고)
도구 이름을 외울 필요는 없습니다. 하고 싶은 걸 말로 시키면 AI가 알아서 고릅니다.
| 분류 | 할 수 있는 일 |
|------|---------------|
| 세션 | Vivado 켜기/끄기, 상태 확인 |
| 프로젝트 | `.xpr` 프로젝트 열기/닫기, 정보 보기 |
| 설계 흐름 | 합성, 구현, 비트스트림 생성 |
| 리포트 | 타이밍 요약, 위반 경로, 리소스 사용량, 클럭, 경고/에러 메시지 |
| 설계 조회 | 모듈 계층, 포트, 넷, 셀 |
| 시뮬레이션 | 시뮬레이션 실행/재시작, 신호 값 읽기, 파형 추가, 브레이크포인트 |
| 고급 | 임의 TCL 명령 실행, 전체 리포트 저장 |
---
원본 프로젝트: [coreyhahn/vivado_mcp](https://github.com/coreyhahn/vivado_mcp)
(Windows 지원: [newtonsart/vivado_mcp](https://github.com/newtonsart/vivado_mcp)) ·
영문 원본 문서: [README.en.md](README.en.md) · License: MIT ([LICENSE](LICENSE))
TDQS
Scored across 40 tools
The tools are mostly cleanly separated by workflow stage: session management, project control, build steps, reporting, design queries, and simulation. A few boundaries are slightly fuzzy, such as get_signal_value versus get_signal_values, session_status versus check_session_health, and the report-generation/read-report pair, but descriptions make the intended use clear.
Names are consistently snake_case and predominantly follow a verb_noun pattern, e.g. run_synthesis, get_timing_summary, launch_simulation, generate_bitstream. Minor deviations like session_status and the singular/plural get_signal_value(s) are readable but keep it from perfect consistency.
Forty tools is heavy for a single MCP surface, even for a complex domain like Vivado. Several simulation and reporting helpers could likely be consolidated or made optional, and the large surface increases selection burden.
The surface covers the core FPGA flow from opening a project through synthesis, implementation, bitstream generation, reporting, and simulation, with run_tcl as an escape hatch. Notable gaps remain around project creation, file/constraint management, IP/block-design operations, and device programming, but most can be worked around via TCL.