Perfonext Build MCP server

perfonext-build-mcp

Analyze Next.js build artifacts to find heavy routes, shared chunks, and bundle growth.

perfonext-build-mcp is a Model Context Protocol (MCP) server that gives GitHub Copilot, Claude Desktop, Claude Code, and other MCP clients structured bundle analysis for Next.js performance work. It loads .next build artifacts and turns them into route-size rankings, shared-chunk and duplication findings, and severity-ranked fix suggestions — evidence agents can reason over instead of inspecting raw .next manifests.

Quick Start

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

Or install globally:

npm install -g @perfonext/build-mcp

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

VS Code

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

{
  "servers": {
    "perfonext-build": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@perfonext/build-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 claudedesktopconfig.json:

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

Restart Claude Desktop to pick up the new server.

Claude Code

Add the server with the CLI:

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

Or add it directly to .mcp.json:

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

Other MCP clients

Any client that supports stdio MCP servers can launch the same command/args pair: command: npx, args: ["-y", "@perfonext/build-mcp"]. Consult your client's docs for where its MCP server configuration file lives.

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

Then ask your assistant: "Load the Next.js build in ./.next and show me the largest routes."

Troubleshooting

spawn npx ENOENT / spawn node ENOENT on macOS with nvm

If the server fails to start with spawn npx ENOENT (or spawn node ENOENT), your editor/app was likely launched from the Dock/Finder and cannot see nvm. GUI apps on macOS do not load shell config (.zshrc/.bashrc), so npx/node installed via nvm are not on PATH. This applies to VS Code, Claude Desktop, and any other GUI MCP client on macOS.

Fix it by giving the MCP config an absolute npx path and a PATH that includes the same Node bin directory (dirname $(which npx)):

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

Merge the command/args/env fields above into your client's server entry (e.g. under servers for VS Code or mcpServers for Claude Desktop/Code).

What It Does

Shortened. The full README is on GitHub.