jmeter-mcp-server

Give an LLM real, deterministic control over Apache JMeter — build test plans, run real load tests, and read back real results, without ever hand-writing .jmx XML or opening the GUI.

"Load test my API: 20 users hitting POST /orders for 2 minutes,
 5% think time, fail anything over 800ms"

...turns into a running JMeter test and a real report, through typed tool calls an MCP client (Claude Code, Claude Desktop, etc.) makes directly.

Why not just ask an LLM to write the .jmx itself?

It can — a .jmx is just XML, and any capable model has seen plenty of JMeter test plans. The problem is how it fails: JMeter's format is a hashTree with dozens of fragile, easy-to-misremember details — exact guiclass/testclass pairs, property names that don't match their GUI label (ThreadGroup.num_threads is a stringProp, not an intProp), integer bitmasks for assertion match types, strict parent/child pairing with sibling <hashTree> tags. None of it is self-checking. A wrong value still produces valid, loadable XML that just quietly does the wrong thing.

That's not hypothetical — it happened building this project. An early version of the If Controller generated a property called useExpression set to true, which reads like "yes, evaluate my condition." The real JMeter source does the opposite: useExpression=true means don't evaluate it as an expression — just check if the string is literally "true". Every non-trivial condition silently, permanently failed. No error, no warning — the child sampler just never ran. It only surfaced by actually executing the generated plan against real JMeter and noticing a sample count of zero.

That's the whole case for this server in one story: an LLM regenerating XML from memory re-risks that exact mistake on every single request. This server encodes the correct shape once, in a serializer (and a matching parser for the reverse direction) checked against real JMeter source and bundled examples, exercised by 166 automated tests including real JMeter runs — and exposes it as typed tools instead. Concretely:

• Correctness through one tested code path, not regenerated-from-memory XML every time.
• Cheap incremental edits. Plans are a small JSON tree with stable node ids — adding, removing, renaming, moving, or disabling an element is one tool call by id, not rewriting a whole .jmx file. An existing .jmx (hand-written or exported from the GUI) can be imported and edited the same way.
• Aggregated results, not raw samples. get_execution_report returns computed stats (error %, avg/median/p90/p95/p99, throughput) — not thousands of sample rows to average by hand.
• Real async execution. execute_test_plan returns immediately with an executionId; long-running load tests never block anything.

The generated .jmx is standard JMeter output — open it in the real GUI any time.

Example

You:    Build a load test: 10 users for 30s hitting GET https://api.example.com/health,
        fail anything that takes over 500ms, then run it and tell me the p95.

Claude: [create_test_plan, add_thread_group, add_http_sampler, add_duration_assertion,
         add_aggregate_report_listener, execute_test_plan, get_execution_status, get_execution_report]

        Ran 300 requests over 30s, 0 failures. p95 latency: 214ms, avg: 187ms, throughput: 10.1 req/s.

Every step above is a real typed MCP tool call — see Tools for the full set (35 element types across samplers, controllers, timers, extractors, assertions, and listeners, plus editing, inspection, and .jmx import/export tools) and Example workflow for the raw call sequence.

Quick start

claude mcp add jmeter \
  -e JMETER_HOME=/opt/homebrew/opt/jmeter/libexec \
  -- npx -y jmeter-mcp-server

That's it — no cloning, no build. Adjust JMETER_HOME to your JMeter install (see Prerequisites). Full setup details, Claude Desktop config, and local-dev instructions are in Adding this server to Claude Code.

How a test plan is represented

Each plan is a JSON tree ({id, type, props, children[]}), not XML text. Authoring tools append a child under a given parentId, editing tools (remove_element, update_element, move_element, etc.) mutate that same tree in place, and the tree is only serialized to a real .jmx file on demand (get_test_plan_xml) or at execution time. import_test_plan runs the reverse direction, parsing an existing .jmx back into this same tree shape. This is what makes incremental edits cheap and keeps all the fiddly XML schema knowledge in two places (src/jmx/serializer.ts for tree → XML, src/jmx/parser.ts for XML → tree, sharing prop shapes from src/jmx/propTypes.ts) instead of spread across every tool.

Tools

Authoring (each returns the new node's id, used as parentId for whatever you attach under it next) — grouped the same way JMeter's own right-click Add menu groups them, so if you already know the GUI, you already know where to look:

Threads (Users):

Sampler:

Logic Controller:

Config Element:

Timer:

Pre Processors:

Post Processors:

Assertions:

Listener:

Editing (mutate an already-built plan):

Inspection:

Execution & reporting (async — a run happens in the background):

Capacity search (async — the search runs many real test executions in the background):

Finding the breaking point

find_breaking_point answers the question JMeter itself has no feature for: how many concurrent users can this survive? Instead of you adjusting the thread count, re-running, reading the report and deciding again — roughly six to eight tool calls per round, across the six to eight rounds a search needs — the server runs the whole search itself and you poll one tool for the answer.

It works in two phases:

1. Bracketing — starts at startThreads and doubles the load (50 → 100 → 200 …) while the SLA holds, until a round breaks it or the maxThreads ceiling is reached.
2. Binary search — bisects between the last healthy level and the first broken one until the two are within toleranceThreads of each other, or maxIterations rounds have run, whichever comes first.

find_breaking_point (planId, threadGroupNodeId, maxThreads: 400, p95Ms: 800, errorPct: 1)
                                → { searchId }
get_breaking_point_status (searchId)   ← poll
                                → { breakingPoint: 137, lastHealthy: 134,
                                    breakingPointRange: { healthyUpTo: 134, brokenAt: 137, exact: false },
                                    stopReason: "converged", progress: {...}, iterations: [...] }

breakingPoint is the lowest load that was actually tested and broke the SLA. Because the search stops bisecting at toleranceThreads, the levels between lastHealthy and breakingPoint were never run — read breakingPointRange for the real precision (exact: true only when the two are adjacent), and treat the edge as "between 134 and 137", not "137". Status also reports progress (rounds done, and the in-flight round's elapsed time and percent complete) and files (where meta.json and the per-round executions live). There is no completion push: poll get_breaking_point_status.

A round passes when every threshold set (p95Ms, errorPct) is met by the overall TOTAL row; at least one threshold is required. Each round puts the thread group into scheduler mode — a ramp-up proportional to the thread count (rampSecondsPerThread) followed by a fixed plateauDurationSeconds at full load — and only the plateau samples count, so the ramp-up doesn't drag the numbers of a healthy round down. Loop counts are deliberately not used: they would make rounds at different thread counts incomparable.

Because a round repeats the thread group's whole scenario until the plateau ends, the request mix per round follows from how the plan is built: a login that should happen once per user belongs under a Once Only Controller (add_once_only_controller), or it will run on every repeat. Each round reports its metrics overall and per label (byLabel, with each label's share of the samples), so a skewed mix is visible right away — the SLA itself is judged on the overall numbers.

The search temporarily overwrites numThreads, rampTimeSeconds, durationSeconds and loops on the thread group you point it at, and restores the original values when it ends — including when it fails or is stopped. The status reports this as propsRestored, and the original values are kept in the search's meta.json in case the process dies mid-search. The plan needs an Aggregate Report, Summary Report, or View Results Tree listener, or there would be no metrics to judge the SLA against.

A search that never breaks the SLA reports breakingPoint: null with stopReason: "ceiling-reached" — raise maxThreads and go again. One where even the first round breaks reports lastHealthy: null; lower startThreads.

While an execution runs, get_execution_status also returns a progress block computed from the results file so far — samples, error rate, avg/p95 latency, overall and recent throughput, and the same per label — so polling it is enough; there is no need to tail stdout.log. Once the run ends, get_execution_report gives the full aggregate.

JSR223 scripts need a compatible Java

JSR223 elements default to Groovy, and the Groovy bundled with JMeter 5.6.x (3.0.x) fails on very new Java releases: every script run throws, which ends that virtual user's iteration and can look like load that never grows. Use Java 17 (LTS) for JMeter — set JAVA_HOME in the MCP server's environment. The add_jsr223_* tools, execute_test_plan and find_breaking_point detect the Java and Groovy versions in use and return a warning / warnings entry when they don't match, and the tool descriptions steer clients toward the built-in ${__UUID}, ${__RandomString} and ${__Random} functions, which need no script.

Example workflow

create_test_plan            → { planId, rootNodeId }
add_thread_group             (parentId: rootNodeId)  → { nodeId: threadGroupId }
add_http_sampler              (parentId: threadGroupId) → { nodeId: samplerId }
add_response_assertion        (parentId: samplerId)
add_aggregate_report_listener (parentId: threadGroupId)
execute_test_plan             (planId) → { executionId }
get_execution_status           (executionId)   ← poll until "completed"
get_execution_report            (executionId) → aggregated latency/error stats

Testing

212 automated tests, no framework beyond Node's built-in test runner:

npm test               # 196 tests: tree-mutation and XML-shape unit tests, XML -> tree parsing,
                        # serialize -> parse round-trips, the breaking-point search algorithm
                        # driven round-by-round against a simulated system, and every tool called
                        # over the real MCP protocol (stdio, the same way Claude Code/Desktop talk
                        # to it) - no JMeter install needed, fully hermetic
npm run test:integration  # 16 tests: real JMeter runs - the If Controller story above, While
                        # Controller loop counts, timer pacing, extractors, assertions, and a full
                        # find_breaking_point search converging on the real concurrency limit of a
                        # live service (needs JMETER_HOME)
npm run test:all

npm test spawns the actual built server (dist/index.js) via StdioClientTransport and drives it exactly as a real client would — not just calling internal functions — so a broken tool schema or a malformed response shows up as a real protocol error, not a passing unit test.

Both suites run on every push and pull request via GitHub Actions — the integration job installs a real JMeter binary on the runner, so it's exercising the same code path as a local run, not a mock.

Prerequisites

• Node.js 18+
• JMeter installed locally, with the JMETER_HOME environment variable pointing at the installation directory (the one containing bin/jmeter). On macOS via Homebrew, brew install jmeter puts it at /opt/homebrew/opt/jmeter/libexec.

Adding this server to Claude Code

Via npx (recommended — published on npm)

No cloning or building required; npx fetches and runs the published version on the fly:

claude mcp add jmeter \
  -e JMETER_HOME=/opt/homebrew/opt/jmeter/libexec \
  -- npx -y jmeter-mcp-server

Adjust the JMETER_HOME path to wherever JMeter is installed on your machine. Optionally set JMETER_MCP_WORKSPACE too (see below) if you want plans and executions stored somewhere other than the default.

The default scope is local (this project directory only). To make it available across every project, add -s user:

claude mcp add jmeter -s user \
  -e JMETER_HOME=/opt/homebrew/opt/jmeter/libexec \
  -- npx -y jmeter-mcp-server

Confirm it registered and is responding:

claude mcp list

From a local clone (development)

If you're working on this repository's code instead of using the published package, point at the built dist/index.js directly:

npm install
npm run build
claude mcp add jmeter \
  -e JMETER_HOME=/opt/homebrew/opt/jmeter/libexec \
  -- node /absolute/path/to/jmeter-mcp-server/dist/index.js

Claude Desktop

Add this to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "jmeter": {
      "command": "npx",
      "args": ["-y", "jmeter-mcp-server"],
      "env": {
        "JMETER_HOME": "/opt/homebrew/opt/jmeter/libexec"
      }
    }
  }
}

Note: unlike a terminal-launched app, Claude Desktop does not inherit environment variables exported in your shell profile (.zshrc, etc.) — only true system-wide ones. Always set JMETER_HOME explicitly in the env block above rather than relying on it already being "set on your machine".

Environment variables

Workspace layout

<workspace>/
  plans/<planId>/plan.json           # JSON tree — source of truth for a plan
  executions/<executionId>/
    generated.jmx                    # serialized at execute_test_plan time
    aggregate-report.jtl             # output of the Aggregate Report listener, if present
    summary-report.jtl               # output of the Summary Report listener, if present
    jmeter.log
    meta.json                        # execution status, pid, timestamps, exit code
  capacity-searches/<searchId>/
    meta.json                        # find_breaking_point search: config, SLA, every round run,
                                     # current bounds, and the thread group's original settings

A find_breaking_point search doesn't get its own execution directory — each of its rounds is a normal execution under executions/, and the search's meta.json records the executionId of every round, so any individual round can still be inspected with get_execution_report.

Editing and importing plans

Beyond the add_* authoring tools, a plan can be mutated after the fact (remove_element, update_element, rename_element, move_element, reorder_children, set_element_enabled) and an externally authored .jmx (e.g. exported from the JMeter GUI) can be brought in with import_test_plan. import_test_plan understands the most common element types (thread groups, HTTP samplers, assertions, extractors, controllers, config elements, the three report listeners, etc.); anything it doesn't recognize is kept as an opaque UnknownElement node whose original XML is preserved and re-emitted as-is by get_test_plan_xml/execute_test_plan, instead of being dropped - import_test_plan's response reports unknownElementCount/ unknownElementTypes so you know what wasn't fully understood. Coverage can be extended incrementally in src/jmx/parser.ts.

v1 scope

Not yet supported (candidates for a future release): generating the HTML dashboard report (-e -o), parent-type validation on add_*/move_element/ import_test_plan (nothing stops attaching an element under a semantically wrong parent), distributed execution.

Note on add_csv_data_set: the filename must be an absolute path. execute_test_plan runs JMeter from a fresh per-execution directory, so a relative path (which JMeter's GUI would resolve against the .jmx file's own location) won't resolve there. An absolute path baked into a plan is also machine-specific — it won't travel if you share plan.json with someone on a different machine. This is only checked at creation time: add_csv_data_set rejects a relative or nonexistent path up front, but later changing a CSVDataSet's filename via update_element, or importing a .jmx that already has a relative one via import_test_plan, is not checked - it will only surface as a failure at execute_test_plan time.

Note on add_jdbc_request/add_jdbc_connection_configuration, add_ftp_request, and add_backend_listener: these generate correct, JMeter-loadable XML, but exercising them for real needs infrastructure this project doesn't provide (a database, an FTP server, an InfluxDB/Graphite instance) — they were verified structurally, not against a real backend.

Note on add_view_results_tree_listener's captureFullData option: it has no effect right now. execute_test_plan always runs JMeter with -Jjmeter.save.saveservice.output_format=csv, and JMeter's CSV writer never emits response body/header columns no matter what the SampleSaveConfiguration flags say — only its XML output format can carry full response bodies. The option is wired up correctly in the generated .jmx (verified: the flags really do flip in the XML) for the day this server supports XML-format runs, but until then it's a no-op — confirmed by running a real capture and checking the resulting JTL has no responseData/samplerData/ requestHeaders/responseHeaders columns regardless of the setting.

Note on add_tcp_sampler: server/port/request are live-verified. The numeric fields (connectTimeoutMs, timeoutMs) are rendered as stringProp following this project's general convention for sampler numeric fields, but that specific choice for TCPSampler wasn't confirmed against a real JMeter-GUI-saved example (none was available to check against) — flagging in case a real save turns out to expect intProp.

Roadmap

Ideas being explored for future releases — none of these are implemented yet:

How this compares

Checked against the other public JMeter MCP servers found on GitHub as of September 3, 2026 — open-source repositories with at least a README description (undocumented forks/clones excluded). Columns reflect what each project's own README documents, not independent verification of its internals.

Every capability in that table shows up somewhere across the other eight projects, individually: real JMeter execution, .jmx generation, traffic import. This is the only one that combines full .jmx round-trip (import and export), per-id incremental editing, non-blocking async execution, and a documented automated test suite in one place.

License

MIT