surfer-mcp

An MCP server that lets AI assistants control Surfer, an open-source waveform viewer for hardware design and verification. It communicates with Surfer over the Waveform Communication Protocol (WCP) and can also read waveform files directly via pywellen.

Features

• Load & reload waveform files (VCD, FST, GHW, etc.)
• Browse hierarchy — list scopes and signals in the design
• Control the viewer — add/remove signals, set cursor position, zoom, set viewport range, add markers, change signal colors
• Read signal data — get values at a timestamp, find edges, search for values, get all transitions in a time window
• Screenshot the Surfer window (macOS)

Requirements

• Python 3.10+
• Surfer installed and on your PATH
• macOS (the screenshot feature uses Quartz; other features work cross-platform if you remove the pyobjc dependency)

Installation

# Clone the repo
git clone https://github.com/PaoloRondot/surfer-mcp.git
cd surfer-mcp

# Install with uv (recommended)
uv pip install -e .

# Or with pip
pip install -e .

Usage with Claude Code

Add to your Claude Code MCP settings (~/.claude/settings.json or project .mcp.json):

{
  "mcpServers": {
    "surfer": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/surfer-mcp", "surfer-mcp"]
    }
  }
}

Or if you installed it globally:

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

Usage with other MCP clients

The server runs over stdio. Start it with:

surfer-mcp

Or without installing:

uv run --directory /path/to/surfer-mcp surfer-mcp

Available Tools