How do I use jmeter-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@jmeter-mcp Run tests/api-load.jmx with 100 threads and show results" 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

An MCP (Model Context Protocol) server that integrates Apache JMeter with AI assistants like Claude Code. Run load tests, parse results, inspect test plans, and compare performance — all through natural language.

Prerequisites

Node.js >= 18
Apache JMeter installed locally (download)

Installation

git clone https://github.com/chung-ta1/jmeter-mcp.git
cd jmeter-mcp
npm install
npm run build

Configuration

Set the JMETER_HOME environment variable to your JMeter installation path:

export JMETER_HOME=/usr/local/opt/jmeter

Or create a .env file in the project root (see .env.example):

JMETER_HOME=/usr/local/opt/jmeter

Usage

Adding to Claude Code

There are three ways to register this MCP server with Claude Code:

Option 1: CLI command (recommended)

claude mcp add jmeter -e JMETER_HOME=/usr/local/opt/jmeter -- node /absolute/path/to/jmeter-mcp/dist/index.js

This adds the server to your project-level config (.claude/mcp.json). To add it globally (available in all projects):

claude mcp add --scope user jmeter -e JMETER_HOME=/usr/local/opt/jmeter -- node /absolute/path/to/jmeter-mcp/dist/index.js

Option 2: Edit settings file manually

Add to ~/.claude.json (global) or .claude/mcp.json (project-level):

{
  "mcpServers": {
    "jmeter": {
      "command": "node",
      "args": ["/absolute/path/to/jmeter-mcp/dist/index.js"],
      "env": {
        "JMETER_HOME": "/usr/local/opt/jmeter"
      }
    }
  }
}

Option 3: From within Claude Code

Run the /mcp slash command inside a Claude Code session, then follow the prompts to add a new stdio server.

Verify it works

After adding, restart Claude Code and run:

claude mcp list

You should see jmeter listed with status connected. Then ask Claude things like:

"Run the load test at ~/tests/api-test.jmx with 50 threads"
"Show me the results from /tmp/jmeter-results.jtl"
"Compare the baseline and current test results"
"List all test plans in my project"
"Inspect the structure of my test plan"

Standalone

JMETER_HOME=/usr/local/opt/jmeter node dist/index.js

The server communicates over stdio using the MCP protocol.

MCP Tools

Tool	Description
`run_test_plan`	Execute a `.jmx` test plan in non-GUI mode and return a results summary
`get_test_results`	Parse and summarize a `.jtl` or `.csv` results file
`list_test_plans`	Find all `.jmx` files in a directory (optionally recursive)
`inspect_test_plan`	Parse a `.jmx` file and return its structure (thread groups, samplers, assertions)
`compare_results`	Compare two result files and show performance metric differences

Tool Examples

Run a test plan with custom parameters:

{
  "tool": "run_test_plan",
  "arguments": {
    "testPlanPath": "/home/user/tests/api-load-test.jmx",
    "threads": 100,
    "duration": 60,
    "rampUp": 10,
    "properties": {
      "server": "api.example.com",
      "port": "8080"
    }
  }
}

Get detailed test results:

{
  "tool": "get_test_results",
  "arguments": {
    "resultsPath": "/tmp/jmeter-results-1234567890.jtl",
    "detailed": true
  }
}

Compare two test runs:

{
  "tool": "compare_results",
  "arguments": {
    "baselinePath": "/tmp/baseline-results.jtl",
    "currentPath": "/tmp/current-results.jtl"
  }
}

Tech Stack

Library	Version	Purpose
TypeScript	^5.7	Language — strict mode, ES2022 target, ESM modules
@modelcontextprotocol/sdk	^1.12	MCP server SDK — `McpServer` high-level API with stdio transport
Zod	^3.24	Schema validation for MCP tool parameters
csv-parse	^5.6	Parse JMeter `.jtl` / `.csv` result files
fast-xml-parser	^4.5	Parse JMeter `.jmx` test plan XML files
dotenv	^17.3	Load environment variables from `.env` files
Vitest	^4.0	Test framework (dev dependency)

Development

npm run dev            # Watch mode — recompiles on changes
npm run build          # One-time TypeScript compilation
npm test               # Run all tests
npx vitest run src/test/services/JMeterService.test.ts  # Run a single test file

Project Structure

src/
├── index.ts              # Entry point: config → server → stdio transport
├── server.ts             # McpServer creation + tool registration wiring
├── config.ts             # Environment config loader (JMETER_HOME)
├── types/index.ts        # Shared interfaces (JtlRecord, OverallStats, AppConfig)
├── tools/
│   ├── testPlan.ts       # run_test_plan, list_test_plans, inspect_test_plan
│   └── results.ts        # get_test_results, compare_results
├── services/
│   └── JMeterService.ts  # Business logic: CLI execution, JTL/XML parsing
├── utils/
│   └── stats.ts          # percentile(), diffPercent() helpers
└── test/
    ├── config.test.ts
    └── services/
        └── JMeterService.test.ts

License

MIT

jmeter-mcp

jmeter-mcp

Prerequisites

Installation

Configuration

Usage

Adding to Claude Code

Option 1: CLI command (recommended)

Option 2: Edit settings file manually

Option 3: From within Claude Code

Verify it works

Standalone

MCP Tools

Tool Examples

Tech Stack

Development

Project Structure

License

Resources

Related MCP Connectors