Vivado MCP Server (Windows-Native)

Vivado MCP Server is a Model Context Protocol (MCP) server that lets LLM clients control a persistent AMD/Xilinx Vivado TCL session on Windows.

It is designed to avoid the pexpect dependency and run reliably on native Windows by using subprocess.Popen plus a background stdout reader thread.

Why use this

• Persistent Vivado process to avoid repeated startup cost.
• Windows-native process handling (no POSIX pseudo-terminal requirement).
• Clean tool API for MCP clients.
• No command prompt popup windows (CREATE_NO_WINDOW).

Requirements

• Windows 10/11
• Python 3.10+
• Vivado installed locally
• uv (recommended) or pip

Quick install

Option A: local development install (uv)

git clone <your-repo-url>
cd vivado-mcp-win
uv sync

Option B: install from package index (when published)

pip install vivado-mcp-win

Vivado path configuration

The server resolves vivado.bat in this order:

1. start_session tool argument vivado_path
2. Environment variable VIVADO_BAT_PATH
3. PATH lookup (vivado.bat or vivado)
4. Fallback C:\VIVADO\2025.2\Vivado\bin\vivado.bat

Recommended: set VIVADO_BAT_PATH explicitly.

PowerShell example:

$env:VIVADO_BAT_PATH = "C:\Xilinx\Vivado\2025.2\bin\vivado.bat"

Run the MCP server

From source checkout:

uv run vivado-mcp

From installed package:

vivado-mcp

Note: this is a stdio MCP server, so it waits for MCP messages from a client. Running it directly in a terminal will appear idle.

MCP client configuration

Use the vivado-mcp command as a stdio server in your MCP client config.

Generic example:

{
	"mcpServers": {
		"vivado": {
			"command": "vivado-mcp",
			"args": [],
			"env": {
				"VIVADO_BAT_PATH": "C:\\VIVADO\\2025.2\\Vivado\\bin\\vivado.bat"
			}
		}
	}
}

If your client runs inside this repository, you can also use:

{
	"mcpServers": {
		"vivado": {
			"command": "uv",
			"args": ["run", "vivado-mcp"],
			"env": {
				"VIVADO_BAT_PATH": "C:\\VIVADO\\2025.2\\Vivado\\bin\\vivado.bat"
			}
		}
	}
}

Exposed MCP tools

• start_session: starts or reuses a persistent Vivado session.
• run_tcl_command: executes TCL in the live session.
• session_status: returns session status and metrics.
• stop_session: stops the running session.

Development

Install dev dependencies:

uv sync --group dev

Run lint:

uv run ruff check .

Run tests:

uv run pytest

Publish checklist

1. Update project URLs in pyproject.toml.
2. Bump version.
3. Build package:

uv build

4. Publish (example with trusted publisher or token):

uv publish

Troubleshooting

• Error Vivado executable not found: set VIVADO_BAT_PATH or pass vivado_path to start_session.
• Session timeout on startup: increase startup timeout in code or ensure Vivado installation is healthy and licensed.
• Import errors in editor for mcp.*: run uv sync and ensure VS Code uses the project virtual environment.