Skip to main content
Glama
Sign In
perfsage-jmeter-mcp

perfsage-jmeter-mcp

by perfsage
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

🎯 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.

Related MCP server: JMeter MCP Server (TypeScript Edition)

⚡ 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

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

🔁 How it works

Step

Tool

Outcome

1️⃣

ensure_environment

Ready runtime (native or Docker)

2️⃣

import_traffic

Clean application Flow (static noise filtered)

3️⃣

correlate_flow + generate_jmx

Replayable JMeter 5.6.3 plan

4️⃣

edit_jmx (optional)

Workload / structure tweaks (burst, loops, JSR223, …)

5️⃣

run_test / discover_workload

Guarded execution + capacity profile

6️⃣

compile_report

Markdown + HTML + JSON, verdict first

💬 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

Tool

What it does

🩺 ensure_environment

Diagnose + heal Java / JMeter / plugins / Docker

🔍 diagnose_environment

Read-only readiness report

📥 import_traffic

HAR / OpenAPI / Postman → Flow

🔗 correlate_flow

Dynamic values → variables + extractors

📝 generate_jmx

Correlated Flow → JMeter 5.6.3 plan

✏️ edit_jmx

Structured ops on an existing plan (new file by default)

🚀 run_test

Execute with always-on guardrails

📈 discover_workload

Adaptive knee-point discovery

📊 analyze_results

JTL → metrics, bottlenecks, p95/p99

✅ evaluate_slo

Gate against slo.properties

☸️ correlate_with_signalpilot

Merge Kubernetes RCA for the test window

📦 compile_report

Unified Markdown + HTML + JSON

Full schemas & sample payloads: docs/TOOLS.md

🛡️ Environment gate (runs first)

Every JMeter-touching tool calls ensure_environment first:

Condition

Action

Java missing / outside 17–21

Download Temurin JDK 21 into ~/.perfsage/jdk/

JMeter missing / &lt; 5.6.3

Download Apache JMeter 5.6.3 + verify ASF SHA-512

Plugins missing

Install jpgc-casutg, jpgc-tst, jpgc-json, jpgc-dummy, perfsage-slo-reporter

Host can’t be provisioned

Fall back to Docker (justb4/jmeter) and say so

Neither works

Structured failure: attempted · failed · values

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

🧩 Ecosystem

Project

Role

Reveal

JTL analysis + chart pack

SLO Reporter

SLO gate format + Backend Listener

SignalPilot

Kubernetes RCA for the test window

perfsage.com

Brand home · Field Notes · tools

🛠️ 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.

Available Tools

12 tools
analyze_resultsA

Summarise a JTL and rank bottleneck findings at p95/p99.

Use after a completed run. Returns summary metrics and findings.

Inputs: results_path (required). Returns: object

compile_reportA

Compile Markdown/HTML/JSON artifacts with a verdict-led summary.

Use after analyze/evaluate. Optionally evaluates SLOs, SignalPilot, and Reveal. For discovery runs, set use_knee_results=true to analyze/SLO the knee step JTL when a knee exists (default remains the last step for compatibility). Returns verdict, written paths, and the report dict.

Inputs: run_id (required), slo_path, namespace, use_reveal, +1 more. Returns: object

correlate_flowA

Detect dynamic values and rewrite the flow with JMeter variables.

Use after import_traffic. Accepts a flow object or a persisted flow_path. Returns the correlation report, rewritten flow, and a new flow_path.

Inputs: flow (required), confidence_floor. Returns: object

correlate_with_signalpilotA

Merge Kubernetes RCA from SignalPilot for a recorded run window.

Use when client-side latency needs server-side explanation. Returns a SignalPilotReport (available=False when the CLI is missing).

Inputs: run_id (required), namespace (required), context. Returns: object

diagnose_environmentA

Read-only environment diagnosis for Java, JMeter, plugins, and Docker.

Use before planning work when you only need readiness details. Returns an EnvironmentReport with ready/java/jmeter/plugins fields.

Inputs: no named parameters. Returns: object

discover_workloadA

Find a capacity knee by stepping concurrency via -Jperfsage.threads.

Calls ensure_environment first. Each step reuses the same plan and overrides thread count/duration through JMeter properties. Returns DiscoveryOutcome plus provisioning and a recorded run_id. Optional run_id must match [A-Za-z0-9._-]{1,64}; collisions require overwrite=true.

Inputs: plan_path (required), run_id, discovery, overwrite, +1 more. Returns: object

edit_jmxA

Apply structured edits to an existing JMX plan and write a new file.

Use after generate_jmx (or with a hand-written single-ThreadGroup plan). The LLM translates natural-language asks into operations such as set_workload (fixed/ramp/stress/burst), change_method, wrap_loop, wrap_while, and add_jsr223. Writes a new plan by default; set overwrite=true only to replace plan_path. Returns path, summary, ops_applied, and next_action.

Inputs: plan_path (required), operations (required), overwrite, output_path. Returns: object

ensure_environmentA

Diagnose and heal the local JMeter runtime (JDK, JMeter, plugins, Docker).

Call when the host may lack a usable runtime. Returns a ProvisionResult describing actions taken and the resulting execution_mode. Set force_docker=true to prefer Docker when docker_available (even if native is ready).

Inputs: force_docker, allow_download. Returns: object

evaluate_sloA

Gate JTL results against an slo.properties file.

Use for CI pass/fail decisions. Returns an SLOVerdict with compliance_pct.

Inputs: slo_path (required), results_path (required). Returns: object

generate_jmxA

Build an Apache JMeter 5.6.3 plan from a correlated flow and workload.

Use after correlate_flow. Accepts a flow object or a persisted flow_path. Returns the written path and inline jmx (or jmx_truncated when the XML exceeds 200_000 characters).

Inputs: flow (required), workload (required), correlation_report (required), output_path. Returns: object

import_trafficA

Import HAR, OpenAPI, or Postman traffic into a normalised Flow.

Use at the start of scripting. kind=auto detects by extension/content. Returns flow JSON plus request_count. Response headers/bodies are omitted unless include_response_detail=true.

Inputs: source_path (required), kind, base_url, include_static, +1 more. Returns: object

run_testA

Execute a JMX plan with always-on guardrails and streamable JTL output.

Calls ensure_environment first. Returns RunResult fields, run_id, and the provisioning block. Loose guardrails require acknowledged_risk (alias i_understand_the_risk). Optional run_id must match [A-Za-z0-9._-]{1,64}; collisions require overwrite=true. force_docker prefers Docker when available.

Inputs: plan_path (required), run_id, overwrite, guardrails, +4 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4.1/5.0

    Scored across 12 tools

    Disambiguation4/5

    Most tools map to distinct pipeline stages (import, correlate, generate, run, analyze, report), but diagnose_environment/ensure_environment and correlate_flow/correlate_with_signalpilot have overlapping names and related purposes. Descriptions clarify the boundaries, so an agent can usually select correctly.

    Naming Consistency4/5

    All tool names are snake_case and verb-first, following a predictable pattern like diagnose_environment, generate_jmx, and evaluate_slo. correlate_with_signalpilot is a minor deviation from the simple verb_noun shape but still fits the overall style.

    Tool Count5/5

    Twelve tools are well-scoped for a JMeter performance-testing workflow. Each tool covers a meaningful stage from environment readiness to traffic import, JMX generation, execution, analysis, SLO evaluation, and reporting, with no obvious bloat.

    Completeness5/5

    The tool surface covers the full load-test lifecycle: environment provisioning, test creation, execution, workload discovery, results analysis, SLO gating, and report compilation. There are no obvious dead ends or missing core operations for the stated domain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • JMeter MCP Server (TypeScript

      vjgit-369
      A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to programmatically create, execute, and analyze Apache JMeter performance tests. It supports automated bottleneck detection, report generation, and distributed testing management through natural language.
      MIT

    • jmeter-mcp

      Realtyka
      F
      license
      Not graded
      quality
      C
      maintenance
      Integrates Apache JMeter with AI assistants to run and manage load tests through natural language. It enables users to execute test plans, parse results, inspect test structures, and compare performance metrics across different runs.
      -