uvx perfsage-jmeter-mcp.
The story every perf engineer knows
It’s Tuesday afternoon. Someone drops a HAR in Slack:
“Can we get a load test on this login flow before Friday?”
You nod. Then the real work starts — and none of it is performance engineering.
| What you wanted | What actually ate the afternoon |
|---|---|
| 🧪 Run a meaningful test | ❌ Find a JDK that isn’t 8, 11, or “whatever IT installed in 2019” |
| 🔗 Replay a login flow | ❌ Hand-write regex extractors for CSRF, JWT, cart IDs |
| 📈 Pick a thread count | ❌ Guess 50 because last quarter’s plan said 50 |
| ✅ Sign off with confidence | ❌ Stare at average latency that looks green while p99 is on fire |
By the time the HTML report opens, you’ve spent more energy on toolchain archaeology than on the question that mattered:
“So what do we do?”
I’ve lived that loop for years. Reveal fixed the analysis side. SLO Reporter fixed the CI gate. SignalPilot fixed the post-deploy war room.
There was still a gap at the start of the funnel:
Who runs JMeter for the agent?
The gap: AI that talks about load tests, but can’t run them
We’re drowning in “AI-powered performance” demos that:
- Chat about percentiles they never measured
- Paste hallucinated JMX XML
- Skip environment setup entirely
- Gate on averages because the prompt said “looks fine”
That’s chatbot theater. I wanted the opposite.
So I built PerfSage JMeter MCP — a Model Context Protocol server that gives Cursor, Claude Desktop, and any MCP-capable agent a full performance-engineering toolkit.
Your LLM doesn’t simulate JMeter.
It operates it.
What “JMeter managed by an LLM” actually means
Connect the MCP once. Then talk like a tech lead:
“Set up the performance environment, import
login_flow.har, correlate it, find capacity, and give me a p95/p99 verdict.”
Behind that sentence, the agent chains real tools:
| Step | Tool | What the agent actually does |
|---|---|---|
| 1️⃣ | ensure_environment | Heals Java 21 + JMeter 5.6.3 + plugins under ~/.perfsage (Docker fallback if needed) |
| 2️⃣ | import_traffic | HAR / OpenAPI / Postman → clean application Flow (static noise filtered) |
| 3️⃣ | correlate_flow + generate_jmx | CSRF / JWT / session IDs → variables + extractors → replayable plan |
| 4️⃣ | run_test / discover_workload | Guarded execution + knee-point capacity discovery |
| 5️⃣ | analyze_results → evaluate_slo → compile_report | Metrics, SLO gate, Markdown/HTML/JSON with verdict first |
Optional extras when you need the rest of the ladder:
- ☸️
correlate_with_signalpilot— merge Kubernetes RCA for the test window - 📊 Reveal charts — when the report needs the visual playbook, not just numbers
Pain → fix (the honest comparison)
| Pain today | With PerfSage JMeter MCP |
|---|---|
| ❌ “Wrong Java / missing JMeter / plugin chaos” | ✅ ensure_environment self-heals under ~/.perfsage — no sudo, no shell-profile edits |
| ❌ Manual regex correlation for every token | ✅ correlate_flow detects CSRF / JWT / session IDs and wires extractors |
| ❌ Guessing thread counts | ✅ discover_workload finds the knee, recommends ~80% sustained load |
| ❌ Average latency gates that lie | ✅ Reports always include p95 + p99 + SLO verdict |
| ❌ Client metrics disconnected from K8s | ✅ Optional SignalPilot RCA + Reveal charts |
A real session (what it feels like)
You: Set up the performance environment.
Agent: ensure_environment → ready=true
Java 21 + JMeter 5.6.3 under ~/.perfsage
You: Import this HAR and correlate the dynamic values.
Agent: import_traffic → N app requests (statics filtered)
correlate_flow → csrf_token, token, cart_id, SESSION…
You: Generate a plan, discover capacity, compile the report.
Agent: generate_jmx → property-driven threads/duration
discover_workload → knee found, recommend sustained load
compile_report → WARN (p99 breached) + next actions
artifacts → ~/.perfsage/runs/<id>/report/No IDE plugin scavenger hunt. No “works on my machine” JDK drama. No pretending the average is the user experience.
60-second setup
Requires Python 3.10+. Prefer uv.
# try it (no install)
uvx perfsage-jmeter-mcp --version
uvx perfsage-jmeter-mcp# install as a user tool (recommended)
uv tool install perfsage-jmeter-mcp
perfsage-jmeter-mcp --version🔌 Cursor / Claude Desktop MCP config
{
"mcpServers": {
"perfsage-jmeter": {
"command": "uvx",
"args": ["perfsage-jmeter-mcp"]
}
}
}Then say the magic sentence:
“Set up the performance environment, then import my HAR and give me a capacity recommendation.”
That’s the whole onboarding.
login_flow.har targets an offline demo host — perfect for correlation / JMX generation. For live run_test smoke, point at a real staging URL or a public API you own permission to hit.
The environment gate (why this doesn’t melt your laptop)
Every JMeter-touching tool calls ensure_environment first:
| Condition | Action |
|---|---|
| Java missing / outside 17–21 | Download Temurin JDK 21 into ~/.perfsage/jdk/ |
| JMeter missing / < 5.6.3 | Download Apache JMeter 5.6.3 + verify ASF SHA-512 |
| Plugins missing | Install Ultimate Thread Group, JSON, dummy, SLO reporter, … |
| Host can’t be provisioned | Fall back to Docker and say so |
| Neither works | Structured failure: attempted · failed · values |
🔒 Nothing writes outside ~/.perfsage (or your working directory). No silent JAVA_HOME mutations. No package-manager side effects on your system Python.
Where this sits on the PerfSage ladder
Prompt → JMeter MCP → JTL → Reveal / SLO Reporter → (prod) SignalPilot
│ │ │ │ │
│ heal+run samples charts+gates K8s RCA
└────────── LLM-operated performance loop ───────────────┘- JMeter MCP — agent-operated scripting + execution (this launch)
- Reveal — JTL → charts, recommendations, shareable report
- SLO Reporter — CI gates on p99, errors, throughput
- SignalPilot — post-deploy Kubernetes RCA
Same philosophy everywhere: make perf data impossible to ignore and easy to act on.
Who this is for
- 🧑💻 Performance engineers tired of setup tax before insight
- 🤖 Teams already living in Cursor / Claude who want tools, not essays
- 🏗️ Platform/SRE folks who want capacity discovery without a week of JMX archaeology
- 🧪 Anyone who still signs off on averages and wants a better habit
Who it’s not for: people looking for another purple “AI dashboard” that never touches a real sampler.
Try it tonight
- ⭐ Star / clone: github.com/perfsage/perfsage-jmeter-mcp
- 📦 PyPI:
perfsage-jmeter-mcp(uvx perfsage-jmeter-mcp) - 🧰 Tool schemas: docs/TOOLS.md
- 🌐 Brand home: perfsage.com
ensure_environment, and run a real flow. If something breaks, open an issue — I'd rather fix a sharp edge than ship another pretty README that lies.
Apache JMeter is a trademark of the Apache Software Foundation. This project is an independent tool and is not affiliated with or endorsed by the ASF.
Field Notes #9 · By Aashish Bajpai