Vivado MCP Server

A Model Context Protocol (MCP) server that enables AI assistants like Claude to directly interact with AMD/Xilinx Vivado FPGA development tools.

Features

• Session Management: Start/stop persistent Vivado TCL sessions (avoids 30s startup per command)
• Project Management: Open/close Vivado projects (.xpr files)
• Design Flow: Run synthesis, implementation, and bitstream generation
• Reports & Analysis: Get timing summaries, utilization reports, and design analysis
• Design Queries: Explore hierarchy, ports, nets, and cells
• Simulation: Control Vivado's integrated simulator (xsim)
• Raw TCL: Execute arbitrary Vivado TCL commands for advanced operations

Requirements

• Python 3.10+
• AMD/Xilinx Vivado installed (tested with 2023.2+)
• Vivado must be in your PATH, or specify the full path when starting a session

Installation

From GitHub

git clone https://github.com/coreyhahn/vivado_mcp.git
cd vivado_mcp
pip install -e .

Configure Claude Code

Add to your Claude Code MCP configuration (~/.claude/claude_desktop_config.json or project-level .mcp.json):

{
  "mcpServers": {
    "vivado": {
      "command": "vivado-mcp"
    }
  }
}

Or if you want to specify the Python interpreter:

{
  "mcpServers": {
    "vivado": {
      "command": "python",
      "args": ["-m", "vivado_mcp"]
    }
  }
}

Usage

Once configured, Claude can interact with Vivado through natural language. Example workflow:

1. Start Vivado session: "Start a Vivado session"
2. Open project: "Open my project at /path/to/project.xpr"
3. Run synthesis: "Synthesize the design"
4. Check timing: "What's the timing summary? Is timing met?"
5. Check utilization: "Show me the resource utilization"
6. Close session: "Stop the Vivado session"

Available Tools

Session Management

• start_session - Start a persistent Vivado TCL session
• stop_session - Stop the Vivado session
• session_status - Get session statistics

Project Management

• open_project - Open a Vivado project (.xpr)
• close_project - Close the current project
• get_project_info - Get project information (part, directory, etc.)

Design Flow

• run_synthesis - Run synthesis
• run_implementation - Run place and route
• generate_bitstream - Generate bitstream

Reports & Analysis

• get_timing_summary - Get timing summary (WNS, TNS, WHS, THS)
• get_timing_paths - Get detailed timing paths for failing/critical paths
• get_utilization - Get resource utilization (LUTs, FFs, BRAMs, DSPs)
• get_clocks - Get clock information
• get_messages - Get synthesis/implementation messages

Design Queries

• get_design_hierarchy - Get module/instance hierarchy
• get_ports - Get top-level ports
• get_nets - Search for nets
• get_cells - Search for cells/instances

Simulation

• launch_simulation - Launch behavioral/post-synth/post-impl simulation
• run_simulation - Run simulation for specified time
• restart_simulation - Restart from time 0
• close_simulation - Close the simulator
• get_simulation_time - Get current simulation time
• get_signal_value - Get a signal's current value
• get_signal_values - Get multiple signal values by pattern
• add_signals_to_wave - Add signals to waveform viewer
• set_simulation_top - Set the testbench module
• get_simulation_objects - List signals in a scope
• get_scopes - List hierarchy scopes
• step_simulation - Step simulation
• add_breakpoint - Add signal breakpoint
• remove_breakpoints - Remove all breakpoints

Advanced

• run_tcl - Execute raw TCL commands
• generate_full_report - Generate full reports to file
• read_report_section - Read portions of large reports
• request_feature - Request new features
• list_feature_requests - List submitted requests

Architecture

┌─────────────────┐     MCP Protocol      ┌─────────────────┐
│   Claude Code   │◄────(JSON-RPC)────────►│  Vivado MCP     │
│   (AI Client)   │     over stdio        │    Server       │
└─────────────────┘                       └────────┬────────┘
                                                   │
                                                   │ pexpect
                                                   │ (TCL commands)
                                                   ▼
                                          ┌─────────────────┐
                                          │ Vivado Process  │
                                          │  (TCL mode)     │
                                          └─────────────────┘

The server maintains a persistent Vivado process in TCL mode. Commands are sent via pexpect and output is captured by waiting for the Vivado prompt. This avoids the ~30 second startup overhead that would occur if Vivado were launched for each command.

Recreating This MCP Server with Claude

This MCP server was created entirely through conversation with Claude. Here's how you can create similar MCP servers:

1. Start with a Clear Goal

Tell Claude what you want to build:

"I want to create an MCP server that lets you control Vivado FPGA tools. You should be able to start Vivado, open projects, run synthesis, check timing, etc."

2. Describe the Architecture

Explain the key technical challenges:

"Vivado takes 30 seconds to start, so we need a persistent session. Vivado has a TCL interface we can use. We need to parse Vivado's text output into structured data."

3. Iterate on Tools

Start with basic tools and add more:

1. Session management (start/stop)
2. Project management
3. Design flow commands
4. Reports and queries
5. Simulation control

4. Key Design Patterns Used

Singleton Session: Only one Vivado process runs at a time

_session: Optional[VivadoSession] = None

def get_session() -> VivadoSession:
    global _session
    if _session is None:
        _session = VivadoSession()
    return _session

pexpect for Process Management: Keeps Vivado alive between commands

self.child = pexpect.spawn(
    f'{self.vivado_path} -mode tcl -nojournal -nolog',
    encoding='utf-8',
    timeout=self.timeout
)
self.child.expect('Vivado%', timeout=10)  # Wait for prompt

Output Parsing: Convert text reports to structured JSON

def parse_timing_summary(output: str) -> dict:
    wns_match = re.search(r"WNS\(ns\)\s*:\s*([-\d.]+)", output)
    if wns_match:
        result["wns"] = float(wns_match.group(1))

Response Truncation: Handle large outputs gracefully

def truncate_response(content: str, max_chars: int) -> dict:
    if len(content) > max_chars:
        return {"content": content[:max_chars], "truncated": True}

5. MCP Server Structure

Every MCP server needs:

from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import Tool, TextContent

server = Server("your-server-name")

@server.list_tools()
async def list_tools() -> list[Tool]:
    return [Tool(name="...", description="...", inputSchema={...})]

@server.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
    # Handle tool calls
    return [TextContent(type="text", text=json.dumps(result))]

async def main():
    async with stdio_server() as (read_stream, write_stream):
        await server.run(read_stream, write_stream,
                        server.create_initialization_options())

6. Prompt for Creating Your Own MCP Server

Use this prompt template with Claude:

I want to create an MCP server for [YOUR TOOL].

Background:
- [Tool] is a [description] that [what it does]
- It has a [CLI/API/etc] interface that accepts [commands/requests]
- Key operations I want to support: [list operations]

Technical considerations:
- [Startup time, persistent state, output formats, etc.]

Please help me create an MCP server with:
1. Session/connection management
2. Core operations as tools
3. Proper error handling
4. Structured JSON responses
5. Comprehensive code comments

Start with the basic structure and we'll iterate from there.

Contributing

Contributions welcome! Please feel free to submit issues and pull requests.

License

MIT License - see LICENSE file for details.

Acknowledgments

• Created with Claude (Anthropic)
• Uses the Model Context Protocol specification
• Integrates with AMD/Xilinx Vivado