PT5 MCP Server

MCP (Model Context Protocol) server for parsing Monsoon Power Monitor PT5 files.

Enables any MCP-compatible client (WorkBuddy, Claude Desktop, Cursor, etc.) to read, analyze, and export power measurement data from .pt5 files captured by Monsoon Solutions' Power Tool software.

Features

• parse_pt5 — Parse a PT5 file and return summary statistics (avg/min/max current, voltage, power, energy)
• get_pt5_channels — List available measurement channels and field types from the captureDataMask
• get_pt5_samples — Retrieve sample data with time-range filtering and decimation
• export_pt5_csv — Export sample data to CSV file for external analysis
• get_pt5_header — Return raw header and status packet metadata (hardware info, calibration, scaling)
• analyze_pt5_trend — Analyze current trend: peak detection, periodicity (autocorrelation), trend segments, anomalies

Quick Start

Use with npx (no install needed)

Add to your MCP client configuration (e.g., ~/.workbuddy/mcp.json or Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "pt5": {
      "command": "npx",
      "args": ["pt5-mcp-server"]
    }
  }
}

Install globally

npm install -g pt5-mcp-server

Then configure:

{
  "mcpServers": {
    "pt5": {
      "command": "pt5-mcp-server"
    }
  }
}

Local development

git clone https://github.com/YOUR_USERNAME/pt5-mcp-server.git
cd pt5-mcp-server
npm install
npm run build

Configure with local path:

{
  "mcpServers": {
    "pt5": {
      "command": "node",
      "args": ["/path/to/pt5-mcp-server/build/index.js"]
    }
  }
}

PT5 File Format

PT5 is the native binary format of Monsoon Solutions' Power Tool software. The file structure is:

Section	Offset	Description
Header	0	212-byte fixed header with capture metadata
Status Packet	272	Variable-length hardware status (calibration, scaling)
Sample Data	1024	Sequential current/voltage samples at 5 kHz

Each sample contains:

• Main Current (signed Int32, µA) — if channel enabled
• USB Current (signed Int32, µA) — if channel enabled
• Aux Current (signed Int32, µA) — if channel enabled
• Voltage (unsigned UInt16, with marker bits) — always present

Voltage tick resolution depends on hardware revision:

Hardware	Main	USB	Aux
Rev A	62.5 µV/tick	62.5 µV/tick	62.5 µV/tick
Rev B	125 µV/tick	125 µV/tick	62.5 µV/tick
Rev C	125 µV/tick	125 µV/tick	125 µV/tick
HVPM	500 µV/tick	125 µV/tick	500 µV/tick

Tools Reference

parse_pt5

Parse a PT5 file and return summary statistics.

Parameters:

• file_path (string, required): Absolute path to the .pt5 file

Returns: JSON with sample count, duration, avg/min/max current (mA), avg voltage (V), avg power (mW), total energy (mJ).

get_pt5_channels

List available measurement channels and fields.

Parameters:

• file_path (string, required): Absolute path to the .pt5 file

Returns: Channels (Main/USB/Aux), fields (Min/Avg/Max Voltage/Current/Power), sample rate, hardware info.

get_pt5_samples

Retrieve sample data with filtering options.

Parameters:

• file_path (string, required): Absolute path to the .pt5 file
• start_time_sec (number, optional): Start time in seconds (default: 0)
• end_time_sec (number, optional): End time in seconds (default: end of capture)
• decimation (number, optional): Return every Nth sample (default: 1)
• max_samples (number, optional): Max samples to return (default: 5000)

Returns: Array of sample objects with timestamp, current (mA), and voltage (V).

export_pt5_csv

Export sample data to a CSV file.

Parameters:

• input_path (string, required): Absolute path to the input .pt5 file
• output_path (string, required): Absolute path for the output .csv file

Returns: Confirmation with file size and sample count.

get_pt5_header

Return raw header and status packet metadata.

Parameters:

• file_path (string, required): Absolute path to the .pt5 file

Returns: Full header and status packet data, including voltage tick sizes per channel.

analyze_pt5_trend

Analyze current trend in a PT5 file: detect periodic peaks, autocorrelation-based periodicity, trend direction, and anomalies.

Parameters:

• file_path (string, required): Absolute path to the .pt5 file
• channel (enum: "main" | "usb" | "aux", optional): Channel to analyze (default: "main")
• peak_window_ms (number, optional): Peak detection window in ms (default: 50)
• min_peak_prominence_ma (number, optional): Minimum peak prominence in mA (default: auto — 5% of mean current)
• anomaly_threshold_std (number, optional): Anomaly detection threshold in standard deviations (default: 3)
• max_lag_sec (number, optional): Maximum lag for autocorrelation in seconds (default: 10)

Returns:

• Basic stats: mean, std, CV, min, max current
• Peak analysis: total peaks, top peaks with time/current/prominence, average peak interval
• Periodicity: dominant period/frequency from autocorrelation, confidence score (0–1)
• Trend: overall direction (rising/falling/stable), slope, segment breakdown
• Anomalies: intervals where current deviates >N standard deviations from mean
• Histogram: current distribution bins

Example output:

=== Trend Analysis: air-mode.pt5 (channel: main) ===
Mean current: 131.854 mA, Std: 82.512 mA, CV: 0.6259

--- Peak Analysis ---
Total peaks detected: 4244
Average peak interval: 0.0531s (std: 0.0073s)
Top peaks: t=4.610s I=3783.4mA, t=4.709s I=2527.3mA ...

--- Periodicity (Autocorrelation) ---
Dominant period: 0.052s (19.2308Hz)
Confidence: 57.3%

--- Overall Trend ---
Trend: stable (slope: -0.0172 mA/s)
Segments: 80 rising, 60 falling, 84 stable (224 total)

--- Anomalies ---
Found 35 anomaly intervals

License

MIT