react-profiler-mcp

Give your AI agent real React performance data. Get specific fixes, not guesses.

"Which components are making my app slow, and how do I fix them?"

— a question your AI agent can now answer with real data

The problem

React DevTools Profiler gives you raw render timings. But staring at a flame graph and knowing exactly what to change in your code are two different things. Most developers either ignore the data or spend hours guessing.

react-profiler-mcp streams live profiler data from your app directly to your AI agent — so instead of a flame graph you can't read, you get this:

ProductList re-renders 47× on this page, averaging 68ms per render.

The root cause is onAddToCart being recreated on every parent render,
which breaks React.memo() on the child. Fix:

  const onAddToCart = useCallback((id) => {
    dispatch({ type: 'ADD', id });
  }, [dispatch]);

That alone should drop renders from 47 to 3.

Related MCP server: react-devtools-mcp

How it works

Your React app                      AI agent
─────────────────                   ────────────────────────
<ProfilerBridge>    →  POST  →    HTTP ingest (:8787)
  records every                          │
  render commit                    in-memory store
                                         │
                                   MCP stdio server
                                         │
                              "analyze_performance" tool
                                         │
                              Cursor / Claude / Copilot
                              reads real samples and
                              gives you targeted fixes

One local Node process handles both sides. The browser POSTs render samples over loopback; your editor connects to the same process over MCP stdio.

Works with any MCP-compatible agent

Quickstart

1. Install the collector

npm install @react-profiler-mcp/react-collector

2. Wrap your app

import { ProfilerBridge } from '@react-profiler-mcp/react-collector';

export function App() {
  return (
    <ProfilerBridge
      ingestUrl="http://127.0.0.1:8787/v1/profile-samples"
      sessionId="my-app"
      profilerId="main-shell"
    >
      <YourApp />
    </ProfilerBridge>
  );
}

3. Add the MCP server to your editor

Cursor / Windsurf / VS Code — add to your project's .cursor/mcp.json or .vscode/mcp.json:

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

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

~/.gemini/settings.json:

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

4. Use your app, then ask

Open your React app and interact with it normally for 30–60 seconds. Then in your AI agent's chat:

Analyze my React app's performance. Which components are
the worst offenders and what exactly should I change?

The agent calls the profiler tools, reads the real samples from your session, and gives you specific fixes — component names, line-level suggestions, and why each change helps.

Next.js

ProfilerBridge uses client hooks. Keep it inside a Client Component:

'use client';

import { ProfilerBridge } from '@react-profiler-mcp/react-collector';

const ingestUrl =
  process.env.NEXT_PUBLIC_PROFILER_INGEST_URL ?? 'http://127.0.0.1:8787/v1/profile-samples';

export default function Page() {
  return (
    <ProfilerBridge ingestUrl={ingestUrl} sessionId="my-next-app" profilerId="page-root">
      {/* page content */}
    </ProfilerBridge>
  );
}

Add to next.config.js:

const nextConfig = {
  transpilePackages: ['@react-profiler-mcp/react-collector'],
};
export default nextConfig;

ProfilerBridge props

MCP tools

The agent can call these tools once connected (names match the server in packages/mcp-server/src/mcp/server.ts):

⚠️ One process rule

Run either a manually started server or the one your editor spawns — not both. Two processes means two separate in-memory stores. MCP will connect to one; the browser posts to the other. Data never meets.

stdio MCP: Your editor usually spawns the server (npx / node …) and owns stdin/stdout for the protocol. You generally do not attach MCP to a server you already started in a separate terminal (that process’s stdio is tied to the shell). For logs, rely on stderr from the editor-spawned process, or run a second terminal only for HTTP debugging (accepting that MCP in the editor will use a different store unless you use a single process — see docs/MCP_USAGE.md).

Quick check — the process logs the ingest URL on stderr (stdout is reserved for MCP when an editor spawns it):

npx -y @react-profiler-mcp/mcp-server

Notes

• Production: React’s <Profiler> still runs onRender in normal production builds (with some overhead). For shipped apps, set enabled={false} (or omit ProfilerBridge) unless you deliberately want field metrics.

• In-memory store. Data resets when the server restarts. This is intentional — it's a dev tool, not a database.

• Loopback only. The ingest listener binds to 127.0.0.1 (see packages/mcp-server/src/index.ts). Override port with env PORT; do not expose the port publicly.

Packages

Contributing

See CONTRIBUTING.md. Issues and PRs welcome.

To run locally:

git clone https://github.com/YOUR_USERNAME/react-profiler-mcp.git
cd react-profiler-mcp
npm install
npm run build
node packages/mcp-server/dist/index.js

Then in another terminal:

npm run dev -w @react-profiler-mcp/demo

Full contributor guide: docs/LOCAL_DEVELOPMENT.md

License

MIT — see LICENSE.