Apache JMeter Load Testing on MCP Server

Overview

This MCP server integrates Apache JMeter into an MCP (Model Context Protocol) workflow so you can run repeatable, automated load tests against services and applications. It accepts JMeter test plans (.jmx), executes them using a hosted JMeter runtime, and exposes test lifecycle controls and artifacts (logs, result files, summary metrics) through an MCP-compatible API. The server is useful for teams that want to coordinate load testing from MCP-aware orchestrators, CI pipelines, or developer tools that depend on the MCP specification.

Using an MCP-backed JMeter runner centralizes load-test execution and artifacts, enabling reproducible performance tests, easier scaling of test workers, and standardized integration into delivery pipelines. The server can be run locally, in containers, or as part of a cluster to simulate traffic patterns, collect performance metrics, and iterate on capacity planning and optimization.

Features

• Accept and run JMeter test plans (.jmx) submitted via MCP-compliant API calls
• Start, stop, and monitor running test jobs with real-time logs and progress
• Persist and expose result artifacts (JTL/CSV), HTML reports, and summary metrics
• Container-friendly: run via Docker for local/dev/test environments
• Integratable with CI pipelines and MCP-aware orchestration tools
• Configurable JMeter runtime (system properties, JVM args, plugins)
• Basic resource and concurrency controls for safe test execution

Installation / Configuration

Clone the repository and run with Docker, or build and run the JVM artifact.

Clone repo:

git clone https://github.com/QAInsights/jmeter-mcp-server.git
cd jmeter-mcp-server

Build and run (Maven example):

# build
mvn clean package

# run (example)
java -jar target/jmeter-mcp-server.jar \
  --server.port=8080 \
  --jmeter.home=/opt/apache-jmeter \
  --storage.path=/var/jmeter/artifacts

Docker:

# build docker image
docker build -t jmeter-mcp-server:latest .

# run container
docker run -d \
  -p 8080:8080 \
  -e JMETER_HOME=/opt/apache-jmeter \
  -v $(pwd)/artifacts:/var/jmeter/artifacts \
  jmeter-mcp-server:latest

Recommended environment variables:

• PORT or server.port — HTTP port to listen on (default: 8080)
• JMETER_HOME — path to JMeter installation inside the runtime
• STORAGE_PATH — where to store uploaded test plans and results
• MAX_CONCURRENT_JOBS — limit on simultaneous test executions
• JVM_OPTS / JMETER_OPTS — extra runtime options for JMeter

Available Resources

• GitHub repository (source, examples, and sample test plans):
  https://github.com/QAInsights/jmeter-mcp-server
• Sample JMeter test plans (.jmx) included in the repo under /examples
• Example client scripts for submitting jobs (curl, Python)
• Basic Grafana/Prometheus integration examples for metric collection (if enabled)

API endpoints (example table)

Note: Exact endpoints and payload formats are available in the repository’s API docs and example clients.

Use Cases

• Continuous Performance Validation in CI

  • Submit a JMeter .jmx as part of a pipeline stage to validate response times and throughput before merging a release. Fail the pipeline if key SLAs are not met.
  • Example: CI steps upload target test plan and call the server to run for 5 minutes; pipeline polls /api/v1/tests/{id} for completion and archives results.

• Staging Environment Load Testing

  • Simulate real-world traffic patterns against a staging cluster using centrally coordinated JMeter workers. Collect JTL files and generate HTML reports for team review.
  • Example: Deploy the MCP server in the same cloud region, trigger multiple test jobs with varied thread groups, and collect consolidated metrics.

• Scalability and Capacity Planning

  • Run graduated load tests to find breaking points and saturation characteristics. Use the server to orchestrate stepped increases in virtual users across runs while storing historical artifacts.
  • Example: Create a series of tests that increase concurrency (100, 500, 1k) and compare latency/throughput trends.

• Automated Smoke & Regression Load Tests

  • Run short smoke load tests on new builds to detect regressions in performance early in the development cycle.
  • Example: Post-deploy hook triggers a 60-second JMeter plan that exercises critical endpoints and reports pass/fail based on p50/p95 thresholds.

Getting Started Examples

Upload & run a test plan (curl):

curl -F "[email protected]" \
     -F "name=smoke-test" \
     http://localhost:8080/api/v1/tests

Check status:

curl http://localhost:8080/api/v1/tests/{jobId}

Download results:

curl -o results.jtl http://localhost:8080/api/v1/tests/{jobId}/results

For detailed API payloads, sample clients, and recommended JMeter configuration snippets, consult the repository README and the examples directory.