# CPU Performance Engineering

Connects a CPU performance engineering knowledge base to your AI client, parsing perf stat logs, Top-down metrics, and compiler vectorisation diagnostics with cited sources.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 1169
- Author: usamahz
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/usamahz/cpu-performance-engineering/tree/HEAD/misc/mcp
- Updated: 2026-10-08
- HTML: https://affpapa.org/en/nevibecode/mcp/cpu-performance-engineering

## What it does

The server turns a hardware optimisation repository into a local indexed reference manual for AI clients. It bundles fourteen reproducible benchmarks alongside editorial research records. During initialization, the process downloads linked documentation, vendor architecture manuals, and arXiv papers, assembling a local full-text index complete with page references.

Rather than delegating raw log analysis to an LLM, the server evaluates performance output directly. It parses `perf stat` tables across text, CSV, and JSON formats, computing branch miss ratios while preserving separation between P-core and E-core counters. It also flags Top-down pipeline bottlenecks and categorises loop vectorisation diagnostics from gcc and clang.

Execution happens locally over stdio via `uvx cpu-perf`. Because the initial launch fetches external packages and compiles the document index, client connections frequently encounter timeouts. Running `uvx cpu-perf --version` once in your shell warms up the environment beforehand.

## Requirements
- Needs: Python and uv (commands run via uvx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add cpu-perf -- uvx cpu-perf
```
uvx runs the command named after the package; if the README names another one, use uvx --from cpu-perf <command>

### Codex

**Platform CLI**
```bash
codex mcp add mcp -- uvx cpu-perf
```
uvx runs the command named after the package; if the README names another one, use uvx --from cpu-perf <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "mcp": {
            "command": "uvx",
            "args": [
                "cpu-perf"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from cpu-perf <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "mcp": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "cpu-perf"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from cpu-perf <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add mcp uvx cpu-perf
```
uvx runs the command named after the package; if the README names another one, use uvx --from cpu-perf <command>

## When to use it
- diagnose execution bottlenecks from raw `perf stat` logs
- resolve failed loop vectorisation warnings from gcc and clang
- interpret hardware performance events using official Intel, AMD, and Arm guides
- evaluate CPU pipeline stalls against Top-down methodology thresholds

## Example prompts
- Inspect this `perf stat -j` report and point out where execution stalls.
- clang reports `-Rpass-missed` on my loop, how can I restructure the memory access?
- Summarize what the architecture guide says about store forwarding stalls.

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md