perfonext-profiler-mcp

Analyze V8 and Chrome CPU profiles to find hotspots in Next.js servers and scripts.

perfonext-profiler-mcp is a Model Context Protocol (MCP) server that gives GitHub Copilot, Claude Desktop, Claude Code, and other MCP clients structured CPU profiling data for Next.js performance work. It loads V8 and Chrome CPU profiles and turns them into hotspot rankings, per-package costs, and source-annotated hot lines — evidence agents can reason over instead of ingesting multi-megabyte profile dumps.

Quick Start

perfonext-profiler-mcp is a standard MCP stdio server, so it works with any MCP-compatible client (GitHub Copilot in VS Code, Claude Desktop, Claude Code, Cursor, and others). Run it directly with npx:

npx -y @perfonext/profiler-mcp

Or install globally:

npm install -g @perfonext/profiler-mcp

The executable command remains perfonext-profiler-mcp after installation.

VS Code

Add the server to .vscode/mcp.json (the workspace MCP configuration file):

{
  "servers": {
    "perfonext-profiler": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@perfonext/profiler-mcp"]
    }
  }
}

Reload the VS Code window and run MCP: List Servers to start it, or accept the trust prompt when it appears.

Claude Desktop

Add the server to claude_desktop_config.json:

{
  "mcpServers": {
    "perfonext-profiler": {
      "command": "npx",
      "args": ["-y", "@perfonext/profiler-mcp"]
    }
  }
}

Restart Claude Desktop to pick up the new server.

Claude Code

Add the server with the CLI:

claude mcp add perfonext-profiler -- npx -y @perfonext/profiler-mcp

Or add the same mcpServers entry to .mcp.json.

Other MCP clients

Any client that supports stdio MCP servers can launch npx -y @perfonext/profiler-mcp. Consult your client's documentation for its MCP server configuration format.

For a locally-built checkout, point command/args at node and the repo's dist/index.js instead.

Troubleshooting

spawn npx ENOENT / spawn node ENOENT on macOS with nvm

If the server fails to start with this error, your GUI MCP client likely cannot see nvm. GUI apps on macOS do not load shell config (.zshrc/.bashrc), so nvm-installed npx/node are not on PATH. Use an absolute npx path and include the same Node directory in PATH:

{
  "servers": {
    "perfonext-profiler": {
      "type": "stdio",
      "command": "/Users/YOU/.nvm/versions/node/v<version>/bin/npx",
      "args": ["-y", "@perfonext/profiler-mcp"],
      "env": {
        "PATH": "/Users/YOU/.nvm/versions/node/v<version>/bin:/usr/bin:/bin"
      }
    }
  }
}

Merge these fields into your client's server entry, under servers for VS Code or mcpServers for Claude Desktop/Code. Then ask your assistant: "How do I capture a CPU profile of my Next.js server?"

What It Does

• loads .cpuprofile files and Chrome trace exports that contain CPU profile data
• identifies the hottest functions by self time, annotated with the originating npm package
• explains caller and callee relationships for a selected function
• reads actual source code for hot functions and annotates each line with V8 sample counts (v0.2.0)
• aggregates CPU self-time per npm package to find expensive third-party dependencies (v0.3.0)
• compares two profiles to surface regressions and improvements
• returns deterministic optimization suggestions for common hotspots
• summarizes loaded profiles so an MCP client can keep context tight

Tools

Every tool result carries a nextStep breadcrumb pointing at the natural follow-up call, so an MCP client can walk the collect → analyze → fix loop without guessing.

Example Prompts

• "How do I capture a CPU profile of my Next.js server?"
• "Load the CPU profile at ./profile.cpuprofile and show me the top hotspots."
• "Which npm packages are consuming the most CPU in this profile?"
• "Explain why processData is expensive in the loaded profile."
• "Show me the actual source lines for processData and mark which lines are hottest."
• "Explain transformResult and include the annotated source code."
• "Compare my baseline and current CPU profiles and tell me what got slower."
• "Suggest optimizations for the top three hotspots."

Deep Tool Reference

// Input
{ "scenario": "next-server" } // or "script"; defaults to "next-server"

// Output
{
  "scenario": "next-server",
  "summary": "Profile a production Next.js server while it handles a single request. ...",
  "command": "node --cpu-prof --cpu-prof-dir=./.perf-profiles ./node_modules/next/dist/bin/next start",
  "steps": [ "...", "load_profile({ filePath: \"./.perf-profiles/<file>.cpuprofile\" })" ],
  "outputDir": "./.perf-profiles",
  "nextStep": "After stopping the server, call load_profile with the .cpuprofile ..."
}

// Input
{ "profileId": "<id>", "functionName": "myFn", "contextLines": 10 }

// Output (per line)
{
  "lineNumber": 42,
  "content": "  for (let i = 0; i < items.length; i++) {",
  "ticks": 18,      // V8 samples that landed on this line
  "isHot": true     // true when ticks >= 50% of peak ticks for this function
}

// Input
{ "profileId": "<id>", "limit": 5 }