JMeter MCP Server

An MCP server for generating, validating, running, and reporting Apache JMeter API performance tests from structured API sources.

The project is designed for SDETs and automation engineers who want LLM-assisted test-plan creation without letting the LLM write arbitrary JMX. The LLM supplies structured MCP tool arguments; TypeScript code validates the input, applies deterministic load policies, renders JMX, and validates the generated file.

Features

• Generate JMeter .jmx plans from OpenAPI files or explicit endpoint details.
• Deterministic test profiles: smoke, baseline, load, spike, stress, soak, and custom.
• Zod-validated MCP tool inputs.
• Guardrails for aggressive load, documented rate limits, and profile mismatch.
• Runtime parameterization for credentials with JMeter properties such as ${__P(API_KEY,)}.
• OS-agnostic JMeter binary resolution through JMETER_BIN, JMETER_HOME, or jmeter on PATH.
• TypeScript runner scripts for individual JMX files, suites, and JTL summary reports.
• GitHub Actions CI for strict TypeScript build and guardrail tests.

Prerequisites

• Node.js >=22
• npm
• Apache JMeter 5.6.x or compatible
• Java supported by your JMeter installation

JMeter can be discovered in one of three ways:

export JMETER_BIN=/absolute/path/to/jmeter

or:

export JMETER_HOME=/absolute/path/to/apache-jmeter

or by having jmeter available on PATH.

Install

npm ci
npm run build:all
npm test

MCP Usage

Build the server:

npm run build

Configure your MCP client to run:

node /absolute/path/to/jmeter-mcp-server/build/index.js

Or use a short command after linking the package locally:

npm link
jmeter-mcp-server

See docs/MCP_CLIENTS.md for Claude, Claude Code, VS Code/Copilot-style, Continue-style, and generic MCP client examples.

Use the high-level tool for deterministic generation:

create_test_plan_from_api_source

Prefer this high-level tool over step-by-step JMX edits. It validates inputs, applies load-profile policy, renders a complete plan, and validates the generated JMX.

Test Profiles

Profile	Users	Ramp-up	Loops	Duration	Notes
smoke	1	1s	1	none	Minimal validation
baseline	5	5s	1	none	Safe default
load	10	30s	3	none	Moderate load
spike	25	1s	1	none	Requires allowAggressiveLoad=true
stress	50	60s	5	none	Requires allowAggressiveLoad=true
soak	5	60s	forever	1800s	Requires allowAggressiveLoad=true
custom	required	optional	optional	optional	Fully explicit

Deterministic profiles reject mismatched overrides. For example, testProfile=baseline with users=6 fails. Use testProfile=custom when you need custom values.

Guardrails

The generation path is intentionally constrained:

LLM request
  -> MCP tool schema
  -> Zod validation
  -> deterministic profile policy
  -> source parsing
  -> normalized test plan model
  -> JMX renderer
  -> generated JMX validation
  -> output file

The MCP rejects:

• missing users for custom profiles
• deterministic profile overrides that do not match policy
• aggressive profiles without allowAggressiveLoad=true
• estimated request rates above a documented OpenAPI rate limit unless explicitly allowed
• malformed headers, placeholder hosts, unsupported protocols, and incomplete request body metadata

Generated JMX validation checks required JMeter components, thread settings, loop settings, duration settings, endpoint target, headers, variables, assertions, and result collectors.

Credentials And Variables

Do not commit .env.

Copy the example locally:

cp .env.example .env

Generated JMX files use JMeter properties and do not need secrets embedded:

${__P(API_KEY,)}
${__P(OAUTH_CLIENT_ID,)}
${__P(OAUTH_CLIENT_SECRET,)}

At runtime, pass values through JMeter properties or set JMETER_ENV_FILE:

JMETER_ENV_FILE=.env npm run jmeter:run -- jmeter/API_Test_Plan_4th_API.jmx results/local-run

Scripts

Build:

npm run build:all

Run guardrail tests:

npm test

Generate JMX suite from OpenAPI:

npm run generate:jmeter:suite -- openapi.yaml jmeter 5

Run one JMX:

npm run jmeter:run -- jmeter/API_Test_Plan_1st_API.jmx results/local-run

Run a suite:

npm run jmeter:suite -- jmeter results/suite

Generate a suite report from JTL files:

npm run jmeter:report -- results/suite/<run-directory>

Rate Limits And Public APIs

Do not run aggressive tests against public or third-party APIs unless the API owner explicitly allows it.

For public practice APIs, prefer smoke or baseline. Profiles such as spike, stress, and soak require explicit opt-in through allowAggressiveLoad=true.

Repository Hygiene

Ignored by default:

• .env, .env.*
• .continue/, .vscode/
• node_modules/
• build/
• results/
• *.log
• *.jtl

Commit-worthy files are source, configuration, docs, workflows, OpenAPI examples, and intentional JMX examples.

Development

npm ci
npm run build:all
npm test

CI runs:

npm run ci

which performs a strict TypeScript build and guardrail tests.

Status

This project is suitable for early public adoption by SDETs who are comfortable with MCP, JMeter, and TypeScript. The core guardrails are deterministic and tested. Additional API source adapters such as Postman collections, HAR files, or GraphQL schemas can be added behind the existing adapter interfaces.