gpu-perf-tune MCP server
Commit Nov 9, 2026Enables AI agents to profile, benchmark, optimize, and report on GPU performance with an emphasis on inference workloads.
Also known as cfregly/gpu-perf-tune
- Stars
- 4
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 9, 2026
- License
- MIT
What is gpu-perf-tune MCP?
gpu-perf-tune enables AI agents to profile, benchmark, optimize, and report on GPU performance with an emphasis on inference workloads.
Summary generated from the project's README
About gpu-perf-tune MCP server
Engineers working on GPU fleet performance can use this tool to profile, benchmark, and optimize inference workloads through AI agents. It provides a comprehensive suite of 32 task-oriented skills designed to handle everything from initial performance estimates to deep kernel profiling and speed-of-light analysis. The system is built to ensure every optimization claim is backed by rigorous evidence, recording hardware, precision, and engine versions to prevent regressions.
Users can deploy this as a bundled MCP server or as a plugin for specific clients like Claude Code and Codex. While it offers best-effort support for Cursor and Gemini CLI, it is primarily optimized for environments where agents can execute complex workflows like inference-kernel-ncu-profile or inference-quantize-calibrate. The server requires suitable GPU hardware and target workloads to perform real runs, and it integrates with external observability tools like Prometheus and zymtrace when credentials are provided.
What you can do with it
- 1Benchmark inference performanceRun load sweeps and engine knob tuning to find optimal performance bounds for a specific model.
- 2Profile GPU kernelsPerform deep analysis of individual kernels using nsys or roofline modeling to identify bottlenecks.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablecfregly/gpu-perf-tune is public and reachablegithub.com/cfregly/gpu-perf-tune ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-09github.com/cfregly/gpu-perf-tune ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubgpu-perf-tune
GPU performance engineering for agents and MCP clients, with an inference-focused skills package and reusable cluster utilities. The project ships 32 task-oriented Agent Skills, a bundled MCP server, safety guards, workload proof schemas, and local validation tools. Together they cover first estimates, benchmark sweeps, kernel profiling, speed-of-light analysis, optimization, and evidence-backed reports.
The work comes from GPU fleet performance practice. Every result stays a candidate until the workload, baseline, hardware, precision, parallelism, and engine version are recorded and the result survives a skeptical check.
Names and boundaries
| Name | Meaning |
|---|---|
gpu-perf-tune |
The project and repository. It owns the skills, MCP server, guards, schemas, examples, and validation. |
profile-and-optimize |
The skills package under plugins/profile-and-optimize/. Claude Code consumes it as a plugin. Codex installs the same skills from a clone. |
profile_and_optimize |
The configured MCP server key. It is usable without the Claude Code plugin. |
profile_and_optimize_mcp |
The Python module that serves the MCP tools and resources. |
Claude Code is one supported client, not the project boundary. Client support depends on the surface being installed.
Client support
| Client | Agent Skills | MCP server | Safety guards |
|---|---|---|---|
| Claude Code | First-class marketplace plugin | Plugin or repo installer | Provenance hook is installed. Enforcement is opt-in |
| Codex | First-class repo installer into ~/.agents/skills |
Repo installer | No client hook adapter. MCP acknowledgement gates still apply |
| Cursor, Gemini CLI, and Antigravity | Best-effort helpers | Best-effort repo installer | No release-tested adapter |
| Other stdio MCP clients | Client-owned discovery | Documented stdio command | No packaged adapter |
The SKILL.md sources follow the open Agent Skills standard. This repository
maintains and tests the Claude Code and Codex paths. The MCP protocol remains
client-neutral. Configuration helpers for other clients are available, but
they are not part of the release bar.
What it covers
- Estimate, benchmark, and sweep:
inference-performance-hintsfor rough performance bounds,inference-perf-benchfor load sweeps,inference-tune-sweepfor engine knobs,inference-model-evalfor quality gates, andperf-baseline-recordwithperf-baseline-difffor regressions. - Profile:
inference-workload-profile,inference-kernel-profilefor nsys,inference-kernel-ncu-profilefor per-kernel roofline work,inference-dcgm-correlate,analyze-zymtrace-workload,inference-graph-diff, andmirage-graph-coverage. - Optimize:
inference-model-optimize,inference-quantize-calibrate, the speculative decode train, tune, and service skills,inference-decode-step-budget,inference-capacity-sizing, andinference-known-good-config. - Report and track:
inference-perf-tune-report,inference-perf-synthesize,inference-fleet-leaderboard,inference-value-ledger,evidence-bundle-init, and the anchored Prometheus and zymtrace query skills.
The documented command-line path remains available when an external observability MCP server is absent.
Quickstart
Inspect the project without a GPU
git clone https://github.com/cfregly/gpu-perf-tune.git
cd gpu-perf-tune
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements/check.txt
make demo
make check
make workload-proof-check
make demo prints the skill and MCP tool surface. A real performance run needs
the bundled server, the target workload, and suitable GPU hardware.
Codex: skills and MCP
From a clone of this repository:
make install-skills CLIENT=codex
make install-mcp CLIENT=codex
codex mcp get profile_and_optimize
The registration check should report enabled: true. Run
make smoke-mcp-runtime for a live server handshake, then restart Codex after
installation. Codex discovers the linked skills under
~/.agents/skills. Use /skills, invoke a skill with $skill-name, or
describe the task and let Codex select one. The MCP configuration is shared by
Codex CLI, the IDE extension, and the desktop app. See the official Codex
Skills and
MCP references for the client-side
contracts.
Claude Code: skills, MCP, and optional provenance enforcement
claude plugin marketplace add cfregly/gpu-perf-tune
claude plugin install --scope user \
profile-and-optimize@profile-and-optimize-plugins
# Install the bundled MCP server inside the current plugin cache entry.
# Add --full when you need the PDF report dependencies.
bash "$(ls -dt ~/.claude/plugins/cache/profile-and-optimize-plugins/profile-and-optimize/*/server/install.sh | head -1)"
claude mcp get plugin:profile-and-optimize:profile_and_optimize
The health check should report Status: ✔ Connected. Restart Claude Code.
Invoke a skill such as /inference-perf-bench, or describe the task and let
Claude Code select a matching skill. The plugin installs its provenance hook,
but the hook remains inactive until
PROVENANCE_COMMIT_GATE=ask or PROVENANCE_COMMIT_GATE=deny is present in the
Claude hook environment. Install jq on PATH before enabling either mode.
Other clients: best-effort helpers
The repository keeps configuration helpers for Cursor, Gemini CLI, and Google Antigravity. They are useful starting points, but changes to those clients do not block a release. The full command list and generic stdio form live in the MCP installation reference.
make install-skills CLIENT=cursor
make install-mcp CLIENT=cursor
Upgrading
Read docs/UPGRADING.md before changing release lines. It
lists the client refresh commands and required installer, AI tuning, MLPerf
rules, and MCP acknowledgement changes.
Value bar
Every benchmark result, optimization claim, and generated report starts as a candidate. It must be adversarially-confirmed to add value before it ships. The workload is named, the baseline is fair, a skeptic has tried to break the finding, and the receipt maps to lower cost, faster runtime, higher throughput, better reliability, or a clearer operator action.
Workload proof contract
docs/workload-proof-packet.md defines the
GPU inference packet shape for neocloud buyers and workflow handoffs.
make workload-proof-check validates checked-in packets for completeness and
local handoff metadata.
Repository layout
| Path | What it is |
|---|---|
plugins/profile-and-optimize/skills/ |
The Agent Skills, one directory per installed skill |
plugins/profile-and-optimize/templates/skill/ |
Starting point for a new skill |
plugins/profile-and-optimize/server/ |
MCP server, tool libraries, contract docs, and report renderer |
plugins/profile-and-optimize/hooks/ |
Runtime-neutral provenance guard plus the Claude Code adapter |
configs/sol-ceilings.yaml |
Datasheet-sourced hardware ceilings used by roofline reports |
examples/workload-proof-packet/ |
Synthetic fixture for packet and handoff validation |
schemas/workload-proof-packet-v1.json |
Public JSON Schema for workload proof packets |
docs/METHODOLOGY.md |
Measurement and reporting rules shared by the skills |
mcp-descriptors/ |
Offline MCP tool-schema snapshots used by skill lint |
Methodology
The skills enforce DRAFT and VERDICT labels, full performance context, asset
validation, and a clear next action. Read
docs/METHODOLOGY.md for the shared rules. The
performance hints adaptation
adds estimate-first triage, with a
synthetic example.
Optional integrations
A workflow system can consume workflow_handoff blocks when GPU workload
evidence needs to attach to a broader customer record. ProofPlane is one
possible consumer. It does not change this project's local contract,
validation gates, or runtime dependencies.
Development
- Add a skill from
plugins/profile-and-optimize/templates/skill/SKILL.md. - Add an MCP verb under
plugins/profile-and-optimize/server/and updatemcp_surface.py. - Read
CONTRIBUTING.mdbefore opening a pull request. - Run
make helpfor the local command reference.
Limitations
The project helps agents measure and report. It does not tune a cluster by itself. Every number depends on the workload and runtime context. Datasheet speed-of-light ceilings are upper bounds, not promises. External systems such as Grafana, Prometheus, GitHub, and zymtrace still need operator credentials and their own client configuration.
License
Project-authored material is MIT licensed. Third-party adaptations
retain their own terms and attribution in
THIRD_PARTY_NOTICES.md and LICENSES/.
gpu-perf-tune MCP questions
Can I use this without a GPU?
Yes, you can inspect the project and run demos without a GPU, but actual performance runs require suitable GPU hardware and a target workload.
Does this tool automatically tune my GPU cluster?
No, the project is designed to help agents measure and report performance; it does not perform autonomous cluster tuning.