perfsage-jmeter-mcp 0.2.1

Self-healing JMeter for LLM agents.
Heal the runtime · auto-correlate scripts · discover capacity · ship a p95/p99 verdict.

🚀 Setup · ✨ Why · 🔁 Flow · 🧰 Tools · 💬 Demo · 🌐 PerfSage

🎯 What you get

Stop wrestling with Java paths, broken plugins, and hand-written extractors.

Point Cursor / Claude at this MCP server and ask for a performance test. It will:

1. Heal Java + Apache JMeter 5.6.3 + plugins under ~/.perfsage (Docker fallback if needed)
2. Import HAR / OpenAPI / Postman traffic
3. Auto-correlate tokens, cookies, and IDs into JMeter variables
4. Discover the throughput knee when you don’t know the workload
5. Report a PASS / WARN / FAIL led by p95 + p99 (never averages alone)

Analysis, not dashboards. Every run ends in a decision.

⚡ 60-second setup

Requires Python 3.10+. Prefer uv (macOS system python3 is often 3.9; uv-managed Pythons also block bare pip via PEP 668).

# 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

# or inside a project venv
uv venv --python 3.12
source .venv/bin/activate   # Windows: .venv\Scripts\activate
uv pip install perfsage-jmeter-mcp

Do not run python3.12 -m pip install … against a uv-managed interpreter — you’ll get externally-managed-environment. Use uv tool install / uv pip install / a venv instead. Apple’s /usr/bin/python3 (3.9) cannot see this package at all (requires-python >=3.10).

🔌 Connect Cursor / Claude Desktop

Drop this into your MCP config (examples/cursor-mcp.json):

{
  "mcpServers": {
    "perfsage-jmeter": {
      "command": "uvx",
      "args": ["perfsage-jmeter-mcp"]
    }
  }
}

Then say:

“Set up the performance environment, then import login_flow.har and give me a capacity recommendation.”

That’s the whole onboarding.

Fixture note: tests/recorder/fixtures/login_flow.har targets shop.perfsage.test, which is offline. Use it to demo correlation / JMX generation only — not live run_test smoke. For runnable demos, import a HAR against a real host (for example JSONPlaceholder or your own staging URL).

✨ Why teams reach for this

🔁 How it works

💬 Example session

You:  Set up the performance environment.
Agent: ensure_environment → ready=true, Java 21 + JMeter 5.6.3 under ~/.perfsage

You:  Import tests/recorder/fixtures/login_flow.har (correlation demo; host is offline) and correlate it.
Agent: import_traffic → 4 app requests
       correlate_flow → csrf_token, token, cart_id, SESSION (cookie-managed)

You:  Generate a fixed plan at 20 threads / 120s, then run a 5-minute burst inside 20 minutes.
Agent: generate_jmx → ${__P(perfsage.threads,20)} / ${__P(perfsage.duration,120)}
       edit_jmx → set_workload burst (Ultimate Thread Group)
       run_test / discover_workload → guarded execution + capacity

You:  Compile the report with examples/slo.properties.
Agent: compile_report → PASS/WARN/FAIL leading with p95 + p99
       artifacts → ~/.perfsage/runs/<id>/report/

🧰 Tools

Full schemas & sample payloads: docs/TOOLS.md

🛡️ Environment gate (runs first)

Every JMeter-touching tool calls ensure_environment first:

🔒 Nothing writes outside ~/.perfsage (or your working directory). No JAVA_HOME mutations. No package-manager side effects.

🧩 Ecosystem

🛠️ Development

uv run --python 3.12 --extra dev pytest
uv run --python 3.12 --extra dev ruff check .
uv run --python 3.12 --extra dev mypy perfsage_jmeter_mcp

Real JMeter e2e: tests/test_end_to_end.py (e2e marker).
Architecture notes: docs/ARCHITECTURE.md

📄 License

MIT

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.

Ready when your agent is.
uvx perfsage-jmeter-mcp · then ask it to ensure_environment