CPU Performance Engineering MCP
The cpu-perf MCP server: an agent answers CPU tuning questions from papers, manuals and benchmarks, with quotes.
- 1,159 ★ on the repository
- Last commit
- MIT
Minimal access
Why this level
- Tools only read, but the server downloads documents from the list links and keeps their index on disk.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add mcp/cpu-performance-engineering-mcpDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewMinimal accessThe tool runs nothing and makes no network calls.
- Tools only read, but the server downloads documents from the list links and keeps their index on disk.
This is third-party code. Review the repository files before installing.
What it does
The CPU Performance Engineering repository keeps an ordered list of sources on fast programs for x86 and Arm, from a single instruction to serving a model on a CPU. The `misc/mcp` folder turns that list into the `cpu-perf` MCP server, which knows two things. The first is the repository itself: entries with their reasons, the list of rejected candidates with the rule they failed, and fourteen benchmarks with code and raw output. The second is the text of the sources. On first start the server downloads documents linked by the list and builds a local index with full-text and semantic search. The main `ask` tool takes a question and whatever output the user pasted: `perf stat`, top-down, `gcc -fopt-info` and `clang -Rpass` remarks, disassembly. The second tool, `read_source`, expands a found passage in full. Answers return quotes with page numbers and state which sources were read and which were not.
Who it is for. Performance and systems engineers who work through `perf` output and compiler remarks and look for a primary source with a reference.
Good fit when
- A multithreaded counter stops scaling past two threads and the causes are needed with references.
- `perf stat` output is pasted into a query to see stalled share and cache miss rates.
- gcc says "not vectorized: complicated access pattern" and you need to know what to change in the loop.
- A reading path for NUMA is needed that ends with a benchmark you can run.
Not a fit when
- You need optimization for a language runtime or database internals, while the list covers the CPU level.
- The client runs in Claude.ai, mobile apps or ChatGPT on the web, and the server starts only locally.
- There is no disk space for a source library of a few hundred megabytes.
Example request
Here is the perf stat output of my program: where does the time go, and what do the list sources say about L3 cache misses?MCP
- Transport
- stdio
- Authentication
- not required
Environment variables
CPU_PERF_DATA_DIR- Directory of the local source library, defaults to the OS data directory.
Limitations
Running needs `uv`. The first start downloads dependencies, and the source index takes from a few minutes to a quarter of an hour to build and occupies up to a few hundred megabytes. Claude Desktop needs the full path to `uvx`. Some publishers such as ACM and IEEE refuse automated clients, and such sources are marked as blocked or partial. The server works only on your machine: Claude.ai, mobile apps and ChatGPT on the web cannot see it.
How to disable. Remove the cpu-perf entry from the MCP configuration (`claude mcp remove cpu-perf`). The source library sits in the data directory (`~/.local/share/cpu-perf` on Linux) and is deleted by hand.
FAQ
How do I connect cpu-perf to Claude Code and Codex?
For Claude Code run `claude mcp add --scope user cpu-perf -- uvx cpu-perf`, for Codex `codex mcp add cpu-perf -- uvx cpu-perf`. For Cursor and VS Code add an entry with the command `uvx` and the argument `cpu-perf` to the configuration.
What does `ask` parse from pasted output?
`perf stat` output in plain, `-x` and `-j` forms with IPC and miss rate calculations, level 1 and 2 top-down, perf's own errors, gcc and clang vectorization remarks and assembly from `objdump`, gdb and `perf annotate`.
How is the source index built?
The server reads the list links, extracts document text with page numbers and builds a local index. Build it with progress using `cpu-perf index`, and `cpu-perf status --detail` shows the state of the sources.
Can I trust the citations?
The server reports which sources were read, which were not and why. A claim is attributed to a source only through a passage that was returned, and an unread source is offered as further reading.
Which clients are not supported?
Claude.ai, Claude mobile apps and ChatGPT on the web. They connect only to servers on the internet, while this one runs as a program on your computer.
Discussion
No questions or reviews yet.
Related
MCP serversRef's MCP server: documentation search for APIs and libraries that hands the agent only the relevant parts of pages
A teaching MCP server in Python: Hacker News search, GitHub repository details and examples of model sampling requests
An MCP server that builds a code graph once and serves the answer to the agent instead of re-reading files
A transparent proxy between an AI client and an MCP server: shows every JSON-RPC frame in the terminal, checks a capture in CI and exports spans
Firmware references for an agent: registers, Modbus and SCPI with a quote and page number, and a refusal instead of a guess when data is missing
The official Arm MCP server: architecture docs search, Arm compatibility scans of code and Docker images, and assembly analysis
README in short
All tools are marked read-only, so clients do not ask for approval on every call. Answers are written as marked-up text for a model, and repeated questions are served from a cache until the library changes.