Pprof Analyzer MCP Server


[]()

This is a Model Context Protocol (MCP) server implemented in Go, providing a tool to analyze Go pprof performance profiles. Built with the official Model Context Protocol Go SDK.

Features

analyze_pprof Tool:
Analyzes the specified Go pprof file and returns serialized analysis results (e.g., Top N list or flame graph JSON).
Supported Profile Types:
cpu: Analyzes CPU time consumption during code execution to find hot spots.
heap: Analyzes the current memory usage (heap allocations) to find objects and functions with high memory consumption. Enhanced with object count, allocation site, and type information.
goroutine: Displays stack traces of all current goroutines, used for diagnosing deadlocks, leaks, or excessive goroutine usage.
allocs: Analyzes memory allocations (including freed ones) during program execution to locate code with frequent allocations. Provides detailed allocation site and object count information.
mutex: Analyzes contention on mutexes to find locks causing blocking. Provides detailed statistics including contention counts, delay times, and percentages.
block: Analyzes operations causing goroutine blocking (e.g., channel waits, system calls). Provides comprehensive blocking statistics with average delay calculations.
Supported Output Formats: text, markdown, json (Top N list), flamegraph-json (hierarchical flame graph data, default).
text, markdown: Human-readable text or Markdown format.
json: Outputs Top N results in structured JSON format (implemented for cpu, heap, goroutine, allocs, mutex, block).
flamegraph-json: Outputs hierarchical flame graph data in JSON format, compatible with d3-flame-graph (implemented for cpu, heap, allocs, default format). Output is compact.
Configurable number of Top N results (top_n, defaults to 5, effective for text, markdown, json formats).
generate_flamegraph Tool:
Uses go tool pprof to generate a flame graph (SVG format) for the specified pprof file, saves it to the specified path, and returns the path and SVG content.
Supported Profile Types: cpu, heap, allocs, goroutine, mutex, block.
Requires the user to specify the output SVG file path.
Important: This feature depends on Graphviz being installed.
open_interactive_pprof Tool (macOS Only):
Attempts to launch the go tool pprof interactive web UI in the background for the specified pprof file. Uses port :8081 by default if http_address is not provided.
Returns the Process ID (PID) of the background pprof process upon successful launch.
macOS Only: This tool will only work on macOS.
Dependencies: Requires the go command to be available in the system's PATH.
Limitations: Errors from the background pprof process are not captured by the server. Temporary files downloaded from remote URLs are not automatically cleaned up until the process is terminated (either manually via disconnect_pprof_session or when the MCP server exits).
detect_memory_leaks Tool:
Compares two heap profile snapshots to identify potential memory leaks.
Analyzes memory growth by object type and allocation site.
Provides detailed statistics on memory growth, including absolute and percentage changes.
Configurable growth threshold and result limit.
Helps identify memory leaks by comparing profiles taken at different points in time.
disconnect_pprof_session Tool:
Attempts to terminate a background pprof process previously started by open_interactive_pprof, using its PID.
Sends an Interrupt signal first, then a Kill signal if Interrupt fails.
compare_profiles Tool:
Compares two profile files (e.g., baseline vs. target) to identify performance regressions or improvements.
Supports all profile types (cpu, heap, allocs, mutex, block).
Provides detailed diff statistics including improved/regressed functions, added/removed functions.
Visual indicators: 🔴 regression, 🟢 improvement, 🆕 added, ❌ removed.
Supports text, markdown, and JSON output formats.
analyze_heap_time_series Tool:
Analyzes multiple heap profiles over time to identify memory growth trends and potential leaks.
Requires at least 3 heap profiles provided in chronological order.
Calculates growth rates (bytes, percentage, MB per minute).
Identifies trending object types with directional indicators (📈 increasing, 📉 decreasing, ➡️ stable).
Supports custom labels for each time point or auto-generates default labels.
* Supports text, markdown, and JSON output formats.

Installation (As a Library/Tool)

You can install this package directly using go install:

go install github.com/ZephyrDeng/pprof-analyzer-mcp@latest

Building from Source

Ensure you have a Go environment installed (Go 1.18 or higher recommended).

In the project root directory (pprof-analyzer-mcp), run:

go build

This will generate an executable file named pprof-analyzer-mcp (or pprof-analyzer-mcp.exe on Windows) in the current directory.

Using go install (Recommended)

You can also use go install to install the executable into your $GOPATH/bin or $HOME/go/bin directory. This allows you to run pprof-analyzer-mcp directly from the command line (if the directory is added to your system's PATH environment variable).

```bash