Waveform Mcp

Waveform MCP Server

[](https://crates.io/crates/waveform-mcp)

An MCP (Model Context Protocol) server for reading and analyzing waveform files (VCD/FST format) using the wellen library.

Usage

Installation

Install via cargo:

cargo install waveform-mcp

The built binary will be at ~/.cargo/bin/waveform-mcp.

Install manually:

# Clone the repository
git clone https://github.com/jiegec/waveform-mcp
cd waveform-mcp

# Build the server
cargo build --release

The built binary will be at target/release/waveform-mcp.

Running

# Run the server with stdio transport (default)
target/release/waveform-mcp

# Run the server in HTTP mode
target/release/waveform-mcp --http

# Run the server in HTTP mode with custom bind address
target/release/waveform-mcp --http --bind-address 0.0.0.0:8000

The server supports two transport modes:

• Stdio mode (default): Uses standard input/output for MCP communication
• HTTP mode: Uses streamable HTTP server for remote access at /mcp endpoint

When running in HTTP mode, the server listens on the specified bind address (default: 127.0.0.1:8000). HTTP mode allows the waveform store to be shared across multiple HTTP sessions, enabling remote analysis of waveform files.

Features

• Open VCD (Value Change Dump) and FST (Fast Signal Trace) waveform files
• List all signals in a waveform with hierarchical paths
• Read the waveform module hierarchy as an indented tree
• Read signal values at specific time indices (single or multiple)
• Get signal metadata (type, width, index range)
• Find signal events (changes) within a time range
• Format time values with timescale information (e.g., "10ns", "5000ps")
• Streamable HTTP server support for remote access

Tools

The server provides 8 MCP tools:

1. open_waveform - Open a waveform file

• file_path: Path to .vcd or .fst file
• alias: Optional alias for the waveform (defaults to filename)

Example response: `` Waveform opened successfully with alias: waveform.vcd ``

1. close_waveform - Close a waveform and free its memory

• waveform_id: ID or alias of the waveform to close

Example response: `` Waveform 'waveform.vcd' closed successfully ``

1. list_signals - List all signals in an open waveform

• waveform_id: ID or alias of the waveform
• name_pattern: Optional substring to filter signals by name (case-insensitive)
• hierarchy_prefix: Optional prefix to filter signals by hierarchy path
• recursive: Optional flag to include signals from sub-hierarchies (default: false)
• limit: Optional maximum number of signals to return (default: 100)

Example response: `` Found 3 signals: top.clock top.reset top.data ``

1. read_hierarchy - Read the waveform module hierarchy as an indented tree

• waveform_id: ID or alias of the waveform
• scope_path: Optional scope path to start from
• recursive: Optional flag to include descendants (default: false)
• limit: Optional maximum number of modules to return (default: 200)

Example response: `` Hierarchy rooted at 'top': top submodule ``

1. read_signal - Read signal values at specific time indices

• waveform_id: ID or alias of the waveform
• signal_path: Hierarchical path to signal (e.g., "top.module.signal")
• time_index: Optional single time index to read
• time_indices: Optional array of time indices to read multiple values

Example response: `` Time index 0 (0ns): 0 Time index 10 (10ns): 1 Time index 20 (20ns): 1 ``

1. getsignalinfo - Get metadata about a signal

• waveform_id: ID or alias of the waveform
• signal_path: Hierarchical path to signal

Example response: `` Signal: top.data Type: Wire Width: 8 bits Index: [7:0] ``

1. findsignalevents - Find all signal changes within a time range

• waveform_id: ID or alias of the waveform
• signal_path: Hierarchical path to signal
• start_time_index: Optional start of time range (default: 0)
• end_time_index: Optional end of time range (default: last time index)
• limit: Optional maximum number of events to return (default: unlimited)

Example response: `` Found 3 events for signal 'top.clock' (time range: 0 to 20): Time index 0 (0ns): 0 Time index 10 (10ns): 1 Time index 20 (20ns): 0 ``

1. findconditionalevents - Find events where a condition is satisfied

• waveform_id: ID or alias of waveform
• condition: Conditional expression to evaluate
• start_time_index: Optional start of time range (default: 0)
• end_time_index: Optional end of time range (default: last time index)
• limit: Optional maximum number of events to return (default: 100)

Example response: `` Found 2 events for condition '!$past(TOP.signal) && TOP.signal' (time range: 0 to 50): Time index 5 (50ns): top.signal = 8'h0A Time index 15 (150ns): top.signal = 8'hFF ``

Supported condition syntax:

• Signal paths (e.g., TOP.signal)
• Bitwise operators: ~ (NOT), & (AND), | (OR), ^ (XOR)
• Boolean operators: && (AND), || (OR), ! (NOT)
• Comparison operators: ==, !=
• Parentheses for grouping: (condition)
• $past(signal) - read signal value from previous time index
• Verilog-style literals: 4'b0101 (binary), 3'd2 (decimal), 5'h1A (hex)
• Bit extraction: signal[bit] for single bit, signal[msb:lsb] for range

Operator precedence (highest to lowest):

1. ~, ! (bitwise NOT, logical NOT)
2. ==, != (equality/inequality)
3. & (bitwise AND)
4. ^ (bitwise XOR)
5. | (bitwise OR)
6. && (logical AND)
7. || (logical OR)

Examples:

• Find when signal1 AND signal2 are true: TOP.signal1 && TOP.signal2
• Find when counter equals a specific value: TOP.counter == 4'd10
• Find rising edge: !$past(TOP.signal) && TOP.signal
• Find falling edge: $past(TOP.signal) && !TOP.signal
• Find handshake cycles (when both valid and ready are asserted): TOP.valid && TOP.ready
• Complex condition: (TOP.valid && TOP.data != 8'hFF) || TOP.error
• Bitwise operations: TOP.flags & 4'b0001 (check if bit 0 is set)
• Bitwise NOT: ~TOP.mask (invert all bits)

Standalone CLI

In addition to the MCP server, a standalone CLI tool waveform-cli is available for direct command-line access without an MCP client.

CLI Usage

# Basic command
waveform-cli open_waveform /path/to/waveform.vcd

# Chain multiple commands with --
waveform-cli open_waveform test.vcd -- list_signals test.vcd --pattern clk

# Full workflow example
waveform-cli open_waveform test.vcd --alias mywave -- \\
  list_signals mywave -- \\
  read_signal mywave top.clk --time-indices 0,1,2,3 -- \\
  close_waveform mywave

CLI Commands

• open_waveform ` [--alias `] - Open waveform file
• close_waveform `` - Close waveform
• list_signals ` [--pattern ] [--hierarchy ] [--recursive ] [--limit `]
• read_hierarchy ` [--scope ] [--recursive ] [--limit `]
• read_signal ` [--time-index | --time-indices `]
• getsignalinfo ` ` - Get signal metadata
• findsignalevents ` [--start ] [--end ] [--limit `]
• findconditionalevents ` [--start ] [--end ] [--limit `]

Development

Building

cargo build
cargo build --release

Testing

cargo test

License

[MIT](LICENSE)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jiegec
• Source: jiegec/waveform-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.