jmeter-mcp-server
This server gives an LLM deterministic control over Apache JMeter: create, edit, run, and analyze JMeter load tests through typed MCP tools without writing JMX.
Author test plans: create TestPlan, thread groups (regular/setUp/tearDown), HTTP/JDBC/JSR223/FTP/TCP samplers, logic controllers, config elements, timers, pre/post-processors, assertions, and listeners.
Edit plans by id: remove, update, rename, move, reorder, enable/disable elements on a JSON tree; import existing
.jmx(unknown elements preserved) and export to JMX.Run real load tests asynchronously: execute a plan, poll status/progress/log, stop runs, and get aggregated per-label/overall stats (error %, avg/min/max/median/p90/p95/p99, throughput, KB/sec).
Find capacity limits: run automated breaking-point searches that ramp concurrency against SLA thresholds (p95/error %) and report the healthy/broken bound.
Inspect workspace: list plans, view full element trees, and serialize any plan to
.jmxXML.
Allows building, maintaining, running, and reading reports for Apache JMeter test plans without the GUI, including creating test plan elements, executing non-GUI load tests, and retrieving aggregated latency/error statistics.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@jmeter-mcp-server Create a test plan hitting https://api.example.com/login with 50 users and show me the report."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.jmxfile. 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_reportreturns computed stats (error %, avg/median/p90/p95/p99, throughput) — not thousands of sample rows to average by hand.Real async execution.
execute_test_planreturns immediately with anexecutionId; long-running load tests never block anything.
The generated .jmx is standard JMeter output — open it in the real GUI any time.
Related MCP server: JMeter MCP Server
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-serverThat'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:
Tool | Adds |
| Root |
Threads (Users):
Tool | Adds |
| Thread Group (virtual users); optional |
| setUp Thread Group (runs once before all Thread Groups) |
| tearDown Thread Group (runs once after all Thread Groups) |
Sampler:
Tool | Adds |
| HTTP Request sampler |
| JDBC Request sampler |
| JSR223 Sampler (Groovy/BeanShell/JS/JEXL script as the sample) |
| FTP Request sampler |
| TCP Sampler |
Logic Controller:
Tool | Adds |
| Transaction Controller (groups child samplers into one named transaction) |
| Loop Controller (repeats child samplers) |
| If Controller (conditionally runs child samplers) |
| While Controller (repeats children while a condition holds) |
| Random Controller (runs one random child per pass) |
| Interleave Controller (alternates through children) |
| Once Only Controller (children run only on each thread's first iteration) |
Config Element:
Tool | Adds |
| CSV Data Set Config (parameterization from a file) |
| User Defined Variables |
| JDBC Connection Configuration (pooled datasource) |
| HTTP Request Defaults |
| HTTP Cookie Manager |
| HTTP Header Manager |
Timer:
Tool | Adds |
| Constant Timer (pacing/think-time) |
| Uniform Random Timer (randomized pacing) |
| Constant Throughput Timer (target rate pacing) |
Pre Processors:
Tool | Adds |
| JSR223 PreProcessor |
| User Parameters (per-thread variable value sets) |
Post Processors:
Tool | Adds |
| JSON Extractor post-processor |
| Regular Expression Extractor post-processor |
| XPath Extractor post-processor |
| JSR223 PostProcessor |
Assertions:
Tool | Adds |
| Response Assertion |
| JSON Assertion (JSONPath validation) |
| Duration Assertion (response-time SLA) |
| Size Assertion (response byte-size check) |
Listener:
Tool | Adds |
| Aggregate Report listener |
| Summary Report listener |
| View Results Tree listener (full request/response capture for debugging) |
| Backend Listener (streams live metrics to InfluxDB/Graphite/etc.) |
Editing (mutate an already-built plan):
Tool | Purpose |
| Remove an element (and its subtree); rejects removing the root |
| Shallow-merge (or replace) a node's props; a prop value of |
| Rename an element's |
| Move an element (and its subtree) to a new parent, optionally at a specific index; rejects moving a node into its own subtree |
| Reorder a node's direct children (must pass an exact permutation of the current children) |
| Enable/disable an element without removing it |
Inspection:
Tool | Purpose |
| List every plan in the workspace |
| Full element tree of a plan, including every node's |
| Serialize a plan to its JMeter |
| Import an externally authored |
Execution & reporting (async — a run happens in the background):
Tool | Purpose |
| Serialize to |
|
|
| Send |
| Aggregated stats (per label + overall) parsed from the run's JTL output |
Capacity search (async — the search runs many real test executions in the background):
Tool | Purpose |
| Find the concurrency level where a plan stops meeting its SLA, by running it over and over and driving one thread group's thread count; returns |
|
|
| Abort a running search, keeping the bounds it had already established |
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:
Bracketing — starts at
startThreadsand doubles the load (50 → 100 → 200 …) while the SLA holds, until a round breaks it or themaxThreadsceiling is reached.Binary search — bisects between the last healthy level and the first broken one until the two are within
toleranceThreadsof each other, ormaxIterationsrounds 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.
Parameter | Default | Purpose |
| (required) | Safety ceiling — the search never runs more threads than this |
| (at least one required) | SLA thresholds a round is judged against |
|
| Load for the first round |
| 2% of | How close the bounds must get before the search stops bisecting |
|
| Ramp-up seconds per thread, so every round adds load at the same rate |
|
| Seconds at full load; only these samples count toward the SLA |
|
| Pause between rounds so the system under test recovers |
|
| Hard cap on rounds, so a slow search still ends |
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 statsTesting
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:allnpm 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_HOMEenvironment variable pointing at the installation directory (the one containingbin/jmeter). On macOS via Homebrew,brew install jmeterputs 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-serverAdjust 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-serverConfirm it registered and is responding:
claude mcp listFrom 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.jsClaude 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
Variable | Required | Purpose |
| Yes | JMeter installation directory (must contain |
| No | Where plans and executions are stored. Defaults to |
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 settingsA 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:
Proposed tool | What it does | Why it's worth it |
| Fits Little's Law / the Universal Scalability Law to collected concurrency vs. throughput vs. latency data, and classifies the bottleneck as contention, coherency, or saturation | JMeter only outputs raw numbers; re-deriving a queueing-theory curve fit through prose reasoning would mean reimplementing nonlinear regression by hand for every question |
| Runs linear regression over the latency/error time series of a long-duration soak test to separate normal noise from a real trend (the classic memory-leak signal) | JMeter's graph shows the curve, but doesn't say whether it's a statistically real degradation or just noise |
| Statistical diff across N executions (not just two), with a significance test for whether a p95 shift is real or noise | A ready-made performance regression gate for CI, instead of someone eyeballing two JSON reports and guessing |
| Automatically detects where warm-up (JIT, connection pools, cold caches) ends, and recomputes metrics only over the steady-state window | Today's overall average is polluted by the first few seconds of a run; JMeter doesn't separate this on its own |
| Re-runs failed samples with backoff and separates "real system error" from "one-off flake" (network timeout, etc.) | Produces a trustworthy error rate for a CI gate, instead of an |
| Runs the same test plan across multiple JMeter injector nodes (master-slave, via | JMeter supports distributed mode, but wiring up remote engines, RMI ports, matching JMeter versions, and merging results across machines is entirely manual today — nobody sets this up for a quick test |
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.
Server | Approach |
| Edit by id | Async run | Tests | Real JMeter |
jmeter-mcp-server (this project) | JSON tree, 34 element types, authored and edited by node id | ✓ | ✓ | ✓ | 212, incl. real runs | ✓ |
Runs an existing | — | ✗ | ✗ | ✗ | ✓ | |
Generates a | ✗ | ✗ | ✗ | ✗ | ✓ | |
Generates a whole plan from one JSON payload, runs it via Docker | ✗ | ✗ | ✗ | ✗ | ✓ | |
Heals the local JMeter runtime, imports HAR/OpenAPI traffic, discovers capacity | — | ✗ | ✗ | ✗ | ✓ | |
Demo project for a tutorial video, 11 fixed tools | ✗ | ✗ | ✗ | ✗ | ✓ | |
Reimplements HTTP load testing in Node — no Apache JMeter underneath | ✗ | ✗ | ✗ | ✗ | ✗ | |
Generates a | ✗ | ✗ | ✗ | ✗ | ✓ | |
Demo script with parameters hardcoded in source, not a general-purpose server | ✗ | ✗ | ✗ | ✗ | ✓ |
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
Available Tools
56 toolsadd_aggregate_report_listenerA
Add an Aggregate Report listener under the given parent (Thread Group or TestPlan). Its output is what get_execution_report reads after a run.
Inputs: planId (required), parentId (required), name, filename.
add_backend_listenerA
Add a Backend Listener under the given parent (Thread Group or TestPlan), streaming live metrics to an external backend (InfluxDB by default) instead of a JTL file. If args is omitted, a ready-to-edit InfluxDB argument set is used - at minimum, edit influxdbUrl before running.
Inputs: planId (required), parentId (required), args, name, +1 more.
add_constant_throughput_timerA
Add a Constant Throughput Timer under the given parent, pacing requests to hit a target rate rather than a fixed per-sample delay.
Inputs: planId (required), parentId (required), targetSamplesPerMinute (required), name, +1 more.
add_constant_timerA
Add a Constant Timer under the given parent to pace requests. Under a Thread Group it delays every sampler in it; under a single sampler it delays only that one, before it fires.
Inputs: planId (required), delayMs (required), parentId (required), name.
add_cookie_managerA
Add an HTTP Cookie Manager under the given parent (usually a Thread Group), so samplers in scope share cookies automatically.
Inputs: planId (required), parentId (required), name, policy, +1 more.
add_csv_data_setA
Add a CSV Data Set Config under the given parent (a Thread Group to feed every sampler in it, or a single sampler to scope it there). Each thread reads one row per iteration, exposing each column as a JMeter variable. The filename must be an absolute path readable on the machine that will run the test (execute_test_plan runs JMeter from a fresh per-execution directory, so relative paths won't resolve).
Inputs: planId (required), filename (required), parentId (required), name, +5 more.
add_duration_assertionA
Add a Duration Assertion under an HTTP sampler, failing the sample if it takes longer than maxDurationMs.
Inputs: planId (required), parentId (required), maxDurationMs (required), name.
add_ftp_requestC
Add an FTP Request sampler under the given parent (usually a Thread Group).
Inputs: planId (required), server (required), filename (required), parentId (required), +9 more.
add_header_managerB
Add an HTTP Header Manager under an HTTP sampler (or a Thread Group, to apply to every sampler in it).
Inputs: planId (required), headers (required), parentId (required), name.
add_http_request_defaultsA
Add HTTP Request Defaults under the given parent (usually a Thread Group or TestPlan root). Any field left blank on a later add_http_sampler call under the same scope falls back to these values.
Inputs: planId (required), parentId (required), name, path, +5 more.
add_http_samplerA
Add an HTTP Request sampler under the given parent node (usually a Thread Group). To inherit protocol, domain or port from an HTTP Request Defaults config element in scope (add_http_request_defaults), leave that argument out of the call - do not pass an empty string or a placeholder, because those fields have no default of their own. Passing an explicit value always overrides the Defaults for that field.
Inputs: name (required), path (required), method (required), planId (required), +5 more.
add_if_controllerA
Add an If Controller under the given parent (usually a Thread Group). Samplers added under it (as its children) only run when the condition evaluates truthy. condition is evaluated as a real JavaScript (Rhino) expression after JMeter substitutes any ${var} references, so comparisons work directly, e.g. '${count} < 10' or '"${status}" == "ok"'.
Inputs: planId (required), parentId (required), condition (required), name, +1 more.
add_interleave_controllerA
Add an Interleave Controller under the given parent (usually a Thread Group). Runs one child (added under it) per pass, alternating through them in order instead of running them all.
Inputs: planId (required), parentId (required), name, ignoreSubControllerBlocks.
add_jdbc_connection_configurationA
Add a JDBC Connection Configuration (pooled datasource) under the given parent, usually the Thread Group or TestPlan root. A JDBC Request references this element's dataSource name.
Inputs: dbUrl (required), driver (required), planId (required), parentId (required), +9 more.
add_jdbc_requestA
Add a JDBC Request sampler under the given parent (usually a Thread Group). dataSource must match a JDBC Connection Configuration's dataSource name added elsewhere in the same plan.
Inputs: query (required), planId (required), parentId (required), dataSource (required), +4 more.
add_json_assertionB
Add a JSON Assertion under an HTTP sampler, to validate a JSONPath expression exists (and optionally matches a value) in the response.
Inputs: planId (required), jsonPath (required), parentId (required), name, +5 more.
add_json_extractorA
Add a JSON Extractor post-processor under an HTTP sampler, to save a value from the JSON response into a variable.
Inputs: name (required), planId (required), parentId (required), jsonPathExpr (required), +2 more.
add_jsr223_postprocessorA
Add a JSR223 PostProcessor under an HTTP sampler (or a Thread Group, to apply to every sampler in it), running a script after the sample. Scripts default to Groovy, which only works when JMeter runs on a compatible Java (17 is the safe choice; the Groovy bundled with JMeter 5.6.x fails on very new Java such as 25+, killing each virtual user on its first script run) - the result carries a "warning" field when this server detects a mismatch. For unique or random data, prefer the built-in functions ${__UUID}, ${__RandomString} and ${__Random}, which need no script at all.
Inputs: planId (required), script (required), parentId (required), name, +2 more.
add_jsr223_preprocessorA
Add a JSR223 PreProcessor under an HTTP sampler (or a Thread Group, to apply to every sampler in it), running a script before the sample. Scripts default to Groovy, which only works when JMeter runs on a compatible Java (17 is the safe choice; the Groovy bundled with JMeter 5.6.x fails on very new Java such as 25+, killing each virtual user on its first script run) - the result carries a "warning" field when this server detects a mismatch. For unique or random data, prefer the built-in functions ${__UUID}, ${__RandomString} and ${__Random}, which need no script at all.
Inputs: planId (required), script (required), parentId (required), name, +2 more.
add_jsr223_samplerA
Add a JSR223 Sampler under the given parent (usually a Thread Group), running a script as the sample itself. Scripts default to Groovy, which only works when JMeter runs on a compatible Java (17 is the safe choice; the Groovy bundled with JMeter 5.6.x fails on very new Java such as 25+, killing each virtual user on its first script run) - the result carries a "warning" field when this server detects a mismatch. For unique or random data, prefer the built-in functions ${__UUID}, ${__RandomString} and ${__Random}, which need no script at all.
Inputs: planId (required), script (required), parentId (required), name, +2 more.
add_loop_controllerA
Add a Loop Controller under the given parent (usually a Thread Group). Samplers added under it (as its children) repeat for the given number of loops each time the controller is reached.
Inputs: planId (required), parentId (required), name, loops.
add_once_only_controllerA
Add a Once Only Controller under the given parent (usually a Thread Group). Its children run only on each thread's first iteration and are skipped on every later one - use it for a login before a looping scenario (or in a Thread Group that loops forever / runs on a scheduler, as find_breaking_point does).
Inputs: planId (required), parentId (required), name.
add_random_controllerA
Add a Random Controller under the given parent (usually a Thread Group). On each pass it runs exactly one randomly chosen child (added under it) instead of all of them.
Inputs: planId (required), parentId (required), name.
add_regex_extractorA
Add a Regular Expression Extractor under an HTTP sampler, to save a value from its response (body, headers, etc.) into a variable using a regex capture group. Use this instead of add_json_extractor for non-JSON (HTML/XML/plain-text) responses.
Inputs: regex (required), planId (required), parentId (required), referenceName (required), +4 more.
add_response_assertionC
Add a Response Assertion under an HTTP sampler, to fail the sample if the response doesn't match.
Inputs: planId (required), parentId (required), patterns (required), not, +3 more.
add_setup_thread_groupA
Add a setUp Thread Group under the TestPlan root. Runs once, before all normal Thread Groups start, regardless of where it sits in the tree - typically used for one-time setup (e.g. login, seeding data).
Inputs: planId (required), parentId (required), numThreads (required), rampTimeSeconds (required), +4 more.
add_size_assertionA
Add a Size Assertion under an HTTP sampler, comparing a response field's byte size against a threshold.
Inputs: size (required), planId (required), parentId (required), name, +2 more.
add_summary_report_listenerB
Add a Summary Report listener under the given parent (Thread Group or TestPlan). Its output is what get_execution_report reads after a run.
Inputs: planId (required), parentId (required), name, filename.
add_tcp_samplerB
Add a TCP Sampler under the given parent (usually a Thread Group), opening a raw TCP connection and sending request data.
Inputs: port (required), planId (required), server (required), request (required), +8 more.
add_teardown_thread_groupA
Add a tearDown Thread Group under the TestPlan root. Runs once, after all normal Thread Groups finish, regardless of where it sits in the tree - typically used for one-time cleanup.
Inputs: planId (required), parentId (required), numThreads (required), rampTimeSeconds (required), +4 more.
add_thread_groupC
Add a Thread Group (virtual users) under the given parent node (usually the TestPlan root).
Inputs: name (required), planId (required), parentId (required), numThreads (required), +4 more.
add_transaction_controllerA
Add a Transaction Controller under the given parent (usually a Thread Group). Samplers added under it (as its children) are timed and reported as a single named transaction instead of separately.
Inputs: name (required), planId (required), parentId (required), includeTimers.
add_uniform_random_timerA
Add a Uniform Random Timer under the given parent to pace requests with a randomized delay: delayMs +/- a random amount up to rangeMs, picked fresh before each sample.
Inputs: planId (required), delayMs (required), rangeMs (required), parentId (required), +1 more.
add_user_defined_variablesA
Add a User Defined Variables config element under the given parent (TestPlan root for global variables, or a Thread Group to scope them there). Values are set once, before the test starts.
Inputs: planId (required), parentId (required), variables (required), name.
add_user_parametersA
Add a User Parameters pre-processor under a Thread Group, assigning each thread a different set of variable values (cycled by thread number), set once at thread start unless perIteration is true. Different from add_user_defined_variables, which sets the same values for every thread.
Inputs: planId (required), parentId (required), valueSets (required), variableNames (required), +2 more.
add_view_results_tree_listenerA
Add a View Results Tree listener under the given parent (Thread Group or TestPlan). Its output is readable via get_execution_report when there's no Aggregate/Summary Report listener present. NOTE: captureFullData currently has no effect - execute_test_plan always runs JMeter with CSV output, and JMeter's CSV writer never emits response body/header columns regardless of this flag (only its XML output format can carry those); this option is a no-op until this server supports XML-format runs.
Inputs: planId (required), parentId (required), name, filename, +1 more.
add_while_controllerA
Add a While Controller under the given parent (usually a Thread Group). Samplers added under it (as its children) repeat while condition holds. Leave condition blank (or 'LAST') to loop while the last sampler in the loop succeeded; otherwise it's a JMeter expression re-evaluated each pass, looping until it evaluates to the literal string 'false'.
Inputs: planId (required), parentId (required), name, condition.
add_xpath_extractorA
Add an XPath Extractor under an HTTP sampler, to save a value from an XML/HTML response into a variable using an XPath expression. Set tolerant=true for real-world (non-strict) HTML.
Inputs: planId (required), parentId (required), xpathQuery (required), referenceName (required), +4 more.
create_test_planA
Create a new JMeter test plan. Returns the planId and the id of its root TestPlan node, which you'll use as parentId for the first thread group.
Inputs: name (required).
execute_test_planA
Start running a test plan with JMeter in non-GUI mode. Returns immediately with an executionId; the run continues in the background. Poll get_execution_status to know when it's done, then call get_execution_report to read the results.
Inputs: planId (required).
find_breaking_pointA
Find the concurrency level where a test plan stops meeting its SLA. Runs the plan over and over on its own, driving one thread group's thread count: first doubling the load until the SLA breaks, then binary-searching between the last healthy level and the first broken one. Returns immediately with a searchId; poll get_breaking_point_status for progress and the final breaking point. The thread group is temporarily switched to ramp-up + fixed-plateau (scheduler) mode for the search and its original settings are restored when the search ends. Requires an Aggregate Report, Summary Report, or View Results Tree listener in the plan. Rounds always run the thread group in scheduler mode with an infinite loop count, so every thread repeats its whole scenario until the plateau ends: a request meant to run once per user (e.g. a login) must sit under a Once Only Controller, and a nested Loop Controller runs its count on every repeat. Each round reports its metrics both overall and per label (byLabel, with each label's share of the samples) - check that the mix matches what the plan intends. The SLA is judged on the overall numbers, not per label.
Inputs: planId (required), maxThreads (required), threadGroupNodeId (required), p95Ms, +7 more.
get_breaking_point_statusA
Check a capacity search started with find_breaking_point: status (running/completed/failed/stopped), progress (rounds completed out of maxIterations, plus the in-flight round's elapsed time and percent complete), the rounds run so far with each one's load and overall + per-label metrics, and - once it finishes - the breaking point, the last healthy load, and a plain-language conclusion. breakingPoint is the lowest load that was tested and broke the SLA, not necessarily the exact edge: read breakingPointRange (healthyUpTo / brokenAt / exact) for the real precision, since levels between the two were never run when toleranceThreads is above 1. There is no completion push - poll this tool. The same data is on disk at files.meta, and each round's raw results are in files.executionsDir//.
Inputs: searchId (required).
get_execution_reportA
Read and aggregate the results of a finished (or still-running) execution, computed from its Aggregate Report / Summary Report listener output: per-label and overall count, error rate, avg/min/max/median/p90/p95/p99 latency, throughput and KB/sec.
Inputs: executionId (required).
get_execution_statusA
Check the status of a test run started with execute_test_plan (running/completed/failed), how long it has been running, and - while it runs - a progress block computed from the results file so far: samples, error rate, avg/p95 latency, overall and recent (last ~10s) throughput, and the same per label. Poll this tool rather than tailing stdout.log. The logTail is JMeter's console output with JVM startup warnings filtered out; JMeter only prints a summary line there about every 30 seconds, so it can stay the same between quick polls. Once the run ends, call get_execution_report for the full aggregate.
Inputs: executionId (required).
get_test_planA
Get the full element tree of a test plan, including every node's id (needed as parentId for add_* tools) and type.
Inputs: planId (required).
get_test_plan_xmlA
Serialize a test plan to its JMeter .jmx XML, without running JMeter.
Inputs: planId (required).
import_test_planA
Import an externally authored .jmx file (e.g. exported from the JMeter GUI) as a new test plan. Element types this server doesn't model are kept as opaque UnknownElement nodes (their original XML is preserved and re-emitted as-is) instead of being dropped - check unknownElementCount/unknownElementTypes in the response to see what wasn't fully understood.
Inputs: filePath (required), name.
list_test_plansA
List all test plans in the workspace.
Inputs: no named parameters.
move_elementA
Move an element (and its subtree) to a new parent, optionally at a specific index among the new parent's children (default: appended last). Rejects moving a node into its own subtree.
Inputs: nodeId (required), planId (required), newParentId (required), index.
remove_elementA
Remove an element (and its subtree) from a test plan. The root TestPlan node cannot be removed.
Inputs: nodeId (required), planId (required).
rename_elementC
Rename an element (its testname in the generated .jmx).
Inputs: name (required), nodeId (required), planId (required).
reorder_childrenA
Reorder a node's direct children. orderedChildIds must be an exact permutation of that node's current children ids.
Inputs: planId (required), parentId (required), orderedChildIds (required).
set_element_enabledA
Enable or disable an element without removing it. A disabled element is skipped by JMeter at run time.
Inputs: nodeId (required), planId (required), enabled (required).
stop_breaking_point_searchA
Stop a running capacity search. Terminates the round in flight, restores the thread group's original settings, and keeps whatever bounds the search had established so far.
Inputs: searchId (required).
stop_executionA
Stop a running test execution (sends SIGTERM to the JMeter process).
Inputs: executionId (required).
update_elementA
Update an element's props with a shallow merge (or full replace). A prop value of null in props removes that key. When the node's type is one of the modeled types, the resulting props are validated against that type's schema (check the type first via get_test_plan).
Inputs: props (required), nodeId (required), planId (required), mode.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 56 tools
Each tool targets a distinct JMeter element or operation: add_* tools for different element types (thread groups, samplers, controllers, timers, assertions, extractors, listeners, config elements), and separate tools for lifecycle operations (create, update, move, remove, execute, report). Even similar tools like add_json_extractor vs add_regex_extractor are clearly differentiated by response format. There is no ambiguity in selecting between them.
All tool names follow a strict verb_noun snake_case pattern: add_* for creation, get_* for retrieval, execute/stop for control, etc. The verb is always first and lowercase, and nouns are descriptive (e.g., add_http_sampler, set_element_enabled, get_execution_report). No camelCase or mixed conventions are present.
With 56 tools, the surface is significantly larger than typical MCP servers (calibration marks 25+ as excessive). While JMeter's complexity justifies a broad set, the count still feels heavy and might overwhelm agents. Some tools could be consolidated (e.g., different extractors could be parameterized), but as-is, the tool count is beyond the 'reasonable' range.
The tool set covers the full JMeter workflow: plan creation/import, element manipulation (add, remove, update, move, enable), execution control (execute, stop, status), and result reporting (aggregate, summary, view results tree). It includes a wide variety of samplers, controllers, timers, assertions, and extractors. The main gap is the lack of a tool to delete a test plan entirely (root node cannot be removed), leaving plans to accumulate. Minor gap, but otherwise comprehensive.
Maintenance
Related MCP Connectors
Free test management over MCP: projects, test cases, plans, runs, environments and tasks.
Manage Timequip projects, tasks, comments, members, and dashboards through MCP.
Read and write Mission Control state via MCP — projects, tasks, subtasks, templates, status updates.
Related MCP Servers
- FlicenseCqualityDmaintenanceA Model Context Protocol server that enables executing and interacting with JMeter tests through MCP-compatible clients like Claude Desktop, Cursor, and Windsurf.2-
- FlicenseCqualityDmaintenanceA Model Context Protocol server that enables execution of JMeter performance tests through AI assistants and MCP-compatible clients like Claude, Cursor, and Windsurf.2-
- FlicenseAqualityDmaintenanceEnables the execution and analysis of JMeter performance tests through MCP-compatible clients. It provides tools for running tests in non-GUI mode, identifying performance bottlenecks, and generating comprehensive insights and visualizations from result files.6-
- FlicenseNot gradedqualityCmaintenanceIntegrates 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.-