Waveform MCP

An MCP server based on the wellen library for reading and analyzing waveform files in VCD/FST formats, providing functions such as signal viewing, value reading, and event searching.

Developer tools Research and data #Waveform analysis #Signal debugging #EDA tools .Rust

rating : 2.5 points

downloads : 4.7K

update time : 2026-01-13

Open Site

What is the Waveform Analysis Server?

The Waveform Analysis Server is a tool specifically designed to process digital circuit simulation waveforms. It can read waveform files in VCD (Value Change Dump) and FST (Fast Signal Trace) formats, allowing you to query signal values, analyze signal changes, and detect specific events, just like operating in a professional waveform viewer.

How to use the Waveform Analysis Server?

Using the Waveform Analysis Server is very simple: First, open a waveform file. Then you can list all signals, query the values of specific signals, obtain signal information, or find events that meet specific conditions. The server supports remote access via the command line or HTTP.

Application scenarios

Scenarios that require viewing and analyzing digital signal waveforms, such as digital circuit design verification, FPGA development and debugging, chip verification, teaching demonstrations, signal integrity analysis, and timing problem troubleshooting.

Main features

Waveform file support

Supports two mainstream waveform formats, VCD and FST, and is compatible with the outputs of most digital simulation tools.

Signal browsing and query

List all signals in a hierarchical structure, support filtering by name or path, and easily find the target signal.

Read signal values at time points

Query the values of signals at specific time points, and support batch queries for a single time point or multiple time points.

Signal event detection

Automatically detect all change events of signals within the specified time range, and quickly locate signal transitions.

Conditional event search

Use Verilog-like expressions to find events that meet complex conditions, such as rising edges and specific values.

Remote access support

Supports the HTTP server mode, allowing remote access to waveform data via the network, which facilitates team collaboration.

Advantages

There is no need to install complex waveform viewer software. You can access waveform data through the command line or API.

Supports conditional expression queries, which can find complex signal patterns.

It is open source and free, developed based on Rust, with high performance, efficiency, and stability.

Supports remote access, which facilitates team sharing and analysis of waveforms.

It is compatible with the MCP protocol and can be integrated into various AI assistants and development tools.

Limitations

Only supports VCD and FST formats, and does not support other waveform formats such as FSDB.

There is no graphical interface, which is suitable for command line and API call scenarios.

Large waveform files may require more memory.

The conditional expression syntax is relatively simple and does not support the complete Verilog syntax.

How to use

Installation and startup

Clone the code repository and compile the server, or directly run the pre-compiled binary file.

Open a waveform file

Use the open_waveform command to open your VCD or FST waveform file.

Browse signals

List all signals in the waveform and use filtering conditions to narrow down the scope.

Query signal values

Read the value of a specific signal at a certain time point.

Analyze signal events

Find signal change events or events that meet conditions.

Usage examples

Debugging clock signals

Check whether the frequency and duty cycle of the clock signal meet expectations.

Verifying the handshake protocol

Check whether the valid and ready signals cooperate correctly without violating the protocol.

Analyzing data flow

Track the transmission process of specific data in the pipeline.

Detecting glitches

Find short pulses (glitches) that appear on the signal.

Frequently Asked Questions

Which waveform file formats are supported?

How to find the rising edge of a signal?

Can multiple waveform files be opened simultaneously?

Which operators are supported in conditional expressions?

How to handle large waveform files?

How to remotely access the waveform server?

Related resources

GitHub Repository

Source code and latest version of the Waveform MCP Server

wellen Library Documentation

Technical documentation of the underlying waveform parsing library

MCP Protocol Specification

Official specification document of the Model Context Protocol

VCD Format Description

Detailed description of the VCD waveform format

🚀 Waveform MCP Server

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

✨ Features

Open VCD (Value Change Dump) and FST (Fast Signal Trace) waveform files
List all signals in a waveform with hierarchical paths
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

📦 Installation

# 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. It uses STDIO for transport. Configure your MCP client accordingly.

💻 Usage Examples

The server provides 6 MCP tools:

Basic Usage

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

2. 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

3. 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

4. get_signal_info - 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]

5. find_signal_events - 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

6. find_conditional_events - 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

Advanced Usage

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):

~, ! (bitwise NOT, logical NOT)
==, != (equality/inequality)
& (bitwise AND)
^ (bitwise XOR)
| (bitwise OR)
&& (logical AND)
|| (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)

📚 Documentation

Building

cargo build
cargo build --release

Testing

cargo test

Running

# Run the server with stdio transport (default)
cargo run

# Run the server in HTTP mode
cargo run -- --http

# Run the server in HTTP mode with custom bind address
cargo run -- --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.