Skip to main content
Glama
jmeter-mcp-server

jmeter-mcp-server

by IAnjaniKr

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.

Related MCP server: JMeter MCP Server

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.

Available Tools

13 tools
add_assertionB

Add an assertion to validate responses

Inputs: type (required), value (required), testfile (required), samplerName (required), +1 more.

add_csv_data_configC

Add a CSV Data Set Config for data-driven testing

Inputs: filename (required), testfile (required), variableNames (required), name, +5 more.

add_http_samplerB

Add an HTTP request sampler to an existing test plan

Inputs: name (required), path (required), method (required), testfile (required), +8 more.

add_timerB

Add a timer for think time / delays between requests

Inputs: type (required), delay (required), testfile (required), name, +1 more.

create_test_planB

Create a new JMeter test plan with a default thread group

Inputs: name (required), numthreads (required), outputfile (required), targethost (required), +2 more.

create_test_plan_from_api_sourceC

Create a JMeter test plan from an API source. Supported sourceType values: openapi, endpoint.

Inputs: outputfile (required), sourceType (required), body, name, +17 more.

create_test_plan_from_openapiB

Create a JMeter test plan from an OpenAPI YAML/JSON file. Use this when the user asks for a plan based on an OpenAPI file.

Inputs: outputfile (required), openapiFile (required), name, loops, +9 more.

delete_elementB

Delete an element from a test plan by name

Inputs: testfile (required), elementName (required).

generate_reportB

Generate an HTML report from JMeter test results

Inputs: inputdir (required), outputdir (required).

list_testsA

List all JMeter test files (.jmx) in a directory

Inputs: directory (required).

read_test_fileA

Read and parse a JMeter test file to show its structure

Inputs: testfile (required).

run_testC

Run a JMeter test plan and return results

Inputs: testfile (required), outputdir.

update_thread_groupB

Update thread group settings (threads, ramp-up, loops, duration)

Inputs: testfile (required), delay, loops, duration, +3 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 13 tools

    Disambiguation3/5

    Most tools have clearly distinct purposes, but the three create_test_plan variants overlap, especially create_test_plan_from_api_source with sourceType=openapi and create_test_plan_from_openapi. The explicit routing hint in the OpenAPI tool description helps, but an agent still faces ambiguity about which creation tool to use.

    Naming Consistency5/5

    All tools follow a consistent snake_case verb_noun pattern, such as add_http_sampler, update_thread_group, and generate_report. Even the longer create_test_plan_from_* names stay predictable and readable.

    Tool Count4/5

    Thirteen tools is within the appropriate range for a JMeter-focused server and covers creation, editing, execution, and reporting. The count is slightly higher than necessary because create_test_plan_from_openapi is largely redundant with create_test_plan_from_api_source.

    Completeness3/5

    The server covers the main JMeter workflow: create/read plans, add core elements, run tests, and generate reports. However, updates are limited to thread group settings; samplers, assertions, timers, and config elements can only be deleted and recreated, which is a notable gap for iterative test editing.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      MCP server for API test case generation from Swagger/OpenAPI specs. Parses Swagger 2.0 and OpenAPI 3.x, generates test cases across 8 categories (positive, negative, boundary, auth, security, idempotency, pagination, business logic), and exports to Postman, TestRail, Allure, k6, pytest, Gherkin, and CSV. Supports internal corporate APIs with auth headers. Auto-saves export files to your working di
      10
      10 npm
      2
      MIT