WCP

MCP server for controlling WCP-compatible waveform viewers — Surfer, VaporView, and GTKWave — through the Waveform Control Protocol (WCP).

Features

• Three viewers supported — Surfer, VaporView, GTKWave with automatic protocol handling
• 23 MCP tools covering the full WCP command surface (load, add signals, navigate, markers, etc.)
• Transparent protocol differences — frame format, greeting order, ID types, and JSON-RPC wrapping handled automatically

Quick Start

1. Install and configure:

   pip install .
   

   Add to your MCP client configuration (e.g., Claude Code settings.json):

   {
     "mcpServers": {
       "wcp": {
         "command": "wcp-mcp",
         "args": []
       }
     }
   }
   

2. Start a WCP-compatible waveform viewer:

   Surfer — create .surfer/config.toml to autostart the WCP server:

   [wcp]
   autostart = true
   address = "127.0.0.1:54321"
   

   Then run surfer.

   VaporView — enable WCP in VS Code settings:

   "vaporview.wcp.enabled": true,
   "vaporview.wcp.port": 54322
   

   Or run VaporView: Start WCP Server from the command palette (Ctrl+Shift+P).

   GTKWave — enable WCP with flags:

   gtkwave --wcp --wcp-port=8765
   

3. Use the MCP tools:

   connect_viewer(viewer="surfer", port=54321)
   load_waveform(path="/path/to/sim.vcd")
   add_signals(variables=["top.clk", "top.data"])
   zoom_to_fit()
   

Tool Reference

Connection Management

Tool	Description
connect_viewer	Connect to a viewer (surfer/vaporview/gtkwave)
disconnect_viewer	Disconnect from current viewer
viewer_status	Get viewer name, connection state, and supported commands

Universal Commands (all viewers)

Tool	Description
load_waveform	Load a VCD/FST/GHW file
reload_waveform	Reload the current waveform
add_signals	Add signals by hierarchical name
add_items	Add signal or scope paths, supports recursive=true
remove_items	Remove displayed items by ID
get_item_list	List all displayed item IDs
get_item_info	Get item details; omit ids to query all items
set_viewport_to	Center viewport on a timestamp
set_viewport_range	Set visible time range
zoom_to_fit	Zoom to fit entire waveform
focus_item	Scroll to make an item visible
set_item_color	Set display color for an item
clear	Remove all displayed items

Conditional Commands

Tool	Surfer	VaporView	GTKWave
add_markers	✓	✗	✓
add_scope	✓	✗	✗
set_cursor	✓	✗	✗
shutdown_viewer	✓	✓	✗
get_viewer_state	✗	✓	✗
get_values_at_time	✗	✓	✗
set_marker	✗	✓	✗
get_marker	✗	✓	✗
set_value_format	✓	✓	✗

Escape Hatch

Tool	Description
send_wcp_command	Send a raw WCP command (method + params)

License

MIT