paolorondot/surfer-mcp

6 stars 3 forks Quality 60 Trend 18

MCP server for controlling Surfer waveform viewer via WCP

Overview

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. - waveform files (VCD, FST, GHW, etc.) - — list scopes and signals in the design - — add/remove signals, set cursor position, zoom, set viewport range, add markers, change signal colors - — get values at a timestamp, find edges, search for values, get all transitions in a time window - the Surfer window (macOS) - 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) Add to your Claude Code MCP settings (~/.claude/settings.json or project .mcp.json): 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.

README

surfer-mcp

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:

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

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

License

MIT

View the full README on GitHub

Install

This server does not publish a one-line install command.

Open the repository installation guide New to MCP? Start with the mcpskill.org guide →

Configuration

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