perfonext-render-mcp

Analyze React render behavior in Next.js apps and apply fixes in the editor.

perfonext-render-mcp is a Model Context Protocol (MCP) server that gives GitHub Copilot, Claude Desktop, Claude Code, and other MCP clients structured, machine-readable React render analysis for Next.js performance work. It turns live capture sessions and React DevTools Profiler exports into component costs, exact rerender causes, and regression diffs — evidence an MCP client can act on directly.

Quick Start

perfonext-render-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/render-mcp

Or install globally:

npm install -g @perfonext/render-mcp

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

VS Code

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

{
  "servers": {
    "perfonext-render": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@perfonext/render-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-render": {
      "command": "npx",
      "args": ["-y", "@perfonext/render-mcp"]
    }
  }
}

Restart Claude Desktop to pick up the new server.

Claude Code

Add the server with the CLI:

claude mcp add perfonext-render -- npx -y @perfonext/render-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/render-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-render": {
      "type": "stdio",
      "command": "/Users/YOU/.nvm/versions/node/v<version>/bin/npx",
      "args": ["-y", "@perfonext/render-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: "Run a render analysis on my app."

What It Does

perfonext-render-mcp is the agent companion to React DevTools Profiler and react-scan — best at machine-readable summaries, exact rerender-cause attribution, source-aware follow-up, and diffing. The loop is collect → analyze → fix, all locally:

• collect — choose live capture (react-scan/lite streams events in real time) or manual DevTools export
• analyze — the MCP returns structured, machine-readable evidence: component costs, rerender causes, commit breakdowns, and regressions
• fix — your MCP client uses that evidence to propose and apply concrete code changes

Note: while a live capture session is active, React DevTools Timeline Profiler will not receive events (react-scan/lite takes over the profiling channel). Calling stop_render_capture restores it.

Capabilities:

• live capture — streams per-commit fiber events from a running React app directly into the MCP over a local HTTP endpoint; no manual export required
• manual export — loads exported React DevTools Profiler JSON files as an alternative input path
• summarizes commits, the most expensive components, and detected render issues in one call
• ranks the hottest commits and shows the top components inside each spike
• identifies the slowest components by total render cost
• highlights components with repeated rerenders, reporting the exact changed props/state/hooks when live capture provides changeDescription data, and falling back to deterministic heuristics otherwise
• annotates ranked components with their source file and line when available
• filters DOM host elements (div, span, …) and unnamed components out of ranked output so findings stay actionable
• compares two render profiles to surface regressions and improvements
• keeps profiles in memory so an MCP client can iterate without re-loading

Tools

Entry point

Live capture

Analysis

Usage Walkthrough

Ask your assistant: "Run a render analysis on my app."

Your MCP client calls begin_render_analysis and asks you to choose:

Option A — Live capture (recommended)

Your MCP client will:

1. Start a capture session (ingest server on 127.0.0.1:7721)
2. Install react-scan as a devDependency if not present
3. Write instrumentation-client.js at your project root with the session snippet
4. Import it from your app's client-side entry point
5. Ask whether you want to interact manually or run a test suite (run_render_capture)
6. Stop the session and run analysis

Running a test suite? Use npx playwright test as usual. react-scan/lite installs __REACT_DEVTOOLS_GLOBAL_HOOK__ itself, so a visible window and the React DevTools extension are not required. The run still yields changeDescription data and dataQuality: "exact".