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

Tool	Description
load_waveform	Load a waveform file into Surfer
reload_waveform	Reload the current waveform
list_scopes	List all scopes (modules/instances) in the hierarchy
list_signals	List signals within a scope
add_signals	Add signals to the viewer by name
add_scope	Add all signals in a scope
add_items / remove_items	Add or remove items by path/ID
get_item_list / get_item_info	Query displayed items
set_cursor	Move the cursor to a timestamp
set_viewport_range / set_viewport_to	Control the visible time range
zoom_to_fit	Zoom to fit all data
add_markers	Add named time markers
focus_item	Scroll to an item
set_item_color	Change signal display color
get_signal_values	Read signal values at a timestamp
find_rising_edge / find_falling_edge	Find next edge of a signal
find_value	Find next occurrence of a specific value
get_transitions	Get all transitions in a time window
get_time_range	Get simulation time range and timescale
screenshot	Capture the Surfer window (macOS)
clear	Clear all items from the viewer
shutdown_surfer	Shut down Surfer

How it works

When a tool is first called, the server automatically:

1. Launches Surfer with WCP enabled
2. Connects over TCP and performs the WCP handshake
3. Sends commands and returns results

The Surfer process stays running between tool calls so you can interactively explore waveforms.

License

MIT