Content
# quartus-mcp
`quartus-mcp` is an MCP server for automating **Altera Quartus II 9.1 SP2** workflows on Windows.
It provides MCP tools for:
- creating Quartus projects
- adding and registering VHDL source files
- invoking Quartus builds through Tcl
- reading compile messages and report output
This was built to help with **CLD / Digital Logic Design coursework**, especially for students working in older lab environments that still use **Quartus II 9.1**.
## Who this is for
This project is mainly for:
- classmates using Quartus II 9.1 in lab
- future **CLD / Digital Logic Design** students
- anyone maintaining small legacy Altera/Quartus coursework projects
- anyone who wants an AI-friendly control layer around old Quartus flows
## Current support
**Tested target:**
- **Altera Quartus II 9.1 SP2**
- Windows local install
- legacy `bin\\quartus_sh.exe` layout
**Not guaranteed yet:**
- Quartus Prime
- newer Intel Quartus releases
- Linux-native Quartus setups
- GUI automation beyond project/build/report workflows
If newer versions work, great — but this repo currently targets **Quartus II 9.1 SP2 first**.
## Features
The MCP server currently exposes tools for:
- `quartus.find_installation`
- `quartus.new_project`
- `quartus.list_project_files`
- `quartus.add_source_file`
- `quartus.build`
- `quartus.read_messages`
- `quartus.read_timing_summary`
- `quartus.status`
## What it actually does
This project does **not** try to fake “full AI control of Quartus.”
More accurately, it provides MCP tools for:
- project creation
- source-file registration
- compile/build execution
- report/message inspection
against **Quartus II 9.1**.
The main control path is **Tcl-driven Quartus automation**, which is more stable for legacy versions than trying to depend on newer CLI assumptions.
## Requirements
- Windows
- Python 3
- Quartus II 9.1 SP2 installed locally
- Access to:
- `quartus_sh.exe`
Typical path:
```text
C:\altera\91sp2\quartus\bin\quartus_sh.exe
```
## Setup
### 1. Clone the repo
```powershell
git clone https://github.com/YOURNAME/quartus-mcp.git
cd quartus-mcp
```
### 2. Create a virtual environment
```powershell
py -3 -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
```
### 3. Create your local config
Copy the example config and edit it:
```powershell
copy config\quartus_mcp.example.json config\quartus_mcp.json
```
Example:
```json
{
"quartusInstallPath": "C:\\altera\\91sp2",
"quartusShPath": "C:\\altera\\91sp2\\quartus\\bin\\quartus_sh.exe",
"defaultProjectRoot": "C:\\Users\\YOURNAME\\Projects\\quartus",
"defaultLanguage": "vhdl"
}
```
## MCP client example
Example Claude Desktop MCP entry:
```json
{
"mcpServers": {
"quartus-mcp": {
"command": "C:\\Users\\YOURNAME\\Projects\\quartus-mcp\\.venv\\Scripts\\python.exe",
"args": [
"C:\\Users\\YOURNAME\\Projects\\quartus-mcp\\app.py"
],
"env": {
"QUARTUS_MCP_CONFIG": "C:\\Users\\YOURNAME\\Projects\\quartus-mcp\\config\\quartus_mcp.json"
}
}
}
}
```
## Screenshots
### MCP connected and live
### Successful Quartus run / status output
### Local MCP server process running
## Smoke-test workflow
A good first end-to-end test is a **Full Adder lab project**.
Example workflow:
1. create a new Quartus project
2. add/register:
- `NAND3_YourName.vhd`
- `NAND4_YourName.vhd`
- `FullAdder_YourName.vhd`
3. set top-level entity to `FullAdder_YourName`
4. run compile
5. inspect errors/warnings
6. iterate until clean
This repo was developed with exactly that kind of legacy coursework flow in mind.
## Known limitations
- currently focused on **Quartus II 9.1 SP2**
- assumes legacy Altera install layout
- Tcl is the primary execution backend
- newer Quartus Prime versions may require different build logic
- GUI-only tasks are out of scope for now
- device programming flows are not the main focus yet
## Safety / publishing notes
Do **not** commit:
- personal MCP wrapper configs
- local backup files
- API tokens
- machine-specific secrets
- private absolute paths unless they are sanitized examples
Keep your real `quartus_mcp.json` local if it contains personal paths you do not want public.
## Why this exists
A lot of class FPGA tooling is old, awkward, and not very automation-friendly. This project is meant to make legacy Quartus coursework less painful, especially when working with AI-assisted coding/planning tools.
If it helps current classmates and future students spend less time fighting Quartus and more time understanding digital logic, it did its job.
## License
MIT
