JMeter MCP Server

🚀 JMeter MCP Server (TypeScript Edition)

A powerful Model Context Protocol (MCP) server that enables AI assistants like Claude to interact with Apache JMeter for performance testing. Built with TypeScript for enhanced type safety and reliability.

✨ Features

🎯 Core Features

• Execute JMeter Tests: Run tests in non-GUI mode with comprehensive options
• GUI Mode: Launch JMeter GUI for test development
• Test Plan Creation: Programmatically create HTTP test plans
• Results Analysis: Advanced parsing and analysis of JTL files
• HTML Reports: Generate beautiful dashboard reports
• Distributed Testing: Execute tests across multiple remote servers

📊 Advanced Analysis

• Performance Metrics: Calculate comprehensive statistics (avg, median, percentiles)
• Bottleneck Detection: Automatically identify slow endpoints and high error rates
• Error Analysis: Group and analyze errors by type and endpoint
• Time Series Data: Generate data for performance visualization
• Recommendations: AI-powered suggestions for performance improvements

🛠️ Management Tools

• Plugin Management: List installed JMeter plugins
• Property Management: Get and set JMeter properties
• Validation: Verify JMeter installation and version

📋 Prerequisites

• Node.js: Version 18 or higher
• JMeter: Apache JMeter 5.0 or higher
• npm or yarn: For package management

🔧 Installation

1. Clone or Download

cd jmeter-mcp-server-ts

2. Install Dependencies

npm install

3. Configure Environment

Create a .env file:

cp .env.example .env

Edit .env and set your JMeter path:

JMETER_HOME=C:/apache-jmeter-5.6.3

4. Build

npm run build

🚀 Usage

With Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "jmeter": {
      "command": "node",
      "args": [
        "C:/Users/YourUser/Documents/jmeter-mcp-server-ts/dist/index.js"
      ],
      "env": {
        "JMETER_HOME": "C:/apache-jmeter-5.6.3"
      }
    }
  }
}

With Cursor / Windsurf

Add to your MCP settings:

{
  "jmeter": {
    "command": "node",
    "args": ["path/to/dist/index.js"],
    "env": {
      "JMETER_HOME": "/path/to/jmeter"
    }
  }
}

🔨 Available Tools

1. validate_jmeter

Validate JMeter installation and get version info.

Example:

Validate my JMeter installation

2. execute_jmeter_test

Execute a test plan in non-GUI mode.

Parameters:

• testPlan: Path to .jmx file
• resultsFile: Path for .jtl results
• logFile: (Optional) Log file path
• reportDir: (Optional) Generate HTML report
• properties: (Optional) JMeter properties
• systemProperties: (Optional) System properties
• remoteHosts: (Optional) For distributed testing

Example:

Run JMeter test from C:/tests/my-test.jmx and save results to C:/results/output.jtl with HTML report in C:/reports

3. launch_jmeter_gui

Launch JMeter GUI for test development.

Example:

Open JMeter GUI with test plan C:/tests/my-test.jmx

4. generate_html_report

Generate HTML dashboard from existing results.

Parameters:

• resultsFile: Path to .jtl file
• outputDir: Directory for HTML report

Example:

Generate HTML report from C:/results/output.jtl to C:/reports/dashboard

5. analyze_test_results

Comprehensive analysis of test results.

Example:

Analyze JMeter results from C:/results/output.jtl

Provides:

• Performance summary (avg, median, percentiles)
• Per-endpoint metrics
• Error analysis
• Bottleneck identification
• Performance recommendations

6. create_http_test_plan

Create a new HTTP test plan programmatically.

Parameters:

• name: Test plan name
• outputPath: Where to save .jmx
• threads: Number of virtual users
• rampUp: Ramp-up period (seconds)
• duration: Test duration (seconds)
• endpoint: URL to test
• method: HTTP method (GET/POST/PUT/DELETE/PATCH)
• headers: (Optional) HTTP headers
• body: (Optional) Request body

Example:

Create a JMeter test plan named "API Load Test" to test https://api.example.com/users with 50 threads, 30 second ramp-up, and 120 second duration. Save it to C:/tests/api-test.jmx

7. execute_distributed_test

Run distributed test across multiple servers.

Parameters:

• testPlan: Path to test plan
• resultsFile: Path for results
• remoteHosts: Array of remote server IPs
• startRemoteServers: Auto-start servers
• stopRemoteServers: Auto-s