🚀 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-stop servers

Example:

Execute distributed test with test plan C:/tests/my-test.jmx across servers 192.168.1.10 and 192.168.1.11

8. list_jmeter_plugins

List all installed JMeter plugins.

Example:

Show me installed JMeter plugins

9. get_jmeter_properties

Get JMeter configuration properties.

Example:

Show JMeter properties

10. set_jmeter_property

Set a JMeter property.

Parameters:

• key: Property name
• value: Property value

Example:

Set JMeter property jmeter.save.saveservice.output_format to xml

📊 Example Workflows

Basic Load Test

1. Create a test plan for https://api.example.com/products with 100 users over 60 seconds
2. Execute the test and save results to C:/results/load-test.jtl
3. Analyze the results and show me bottlenecks
4. Generate an HTML report in C:/reports/load-test

Advanced Analysis

Analyze the JMeter results from C:/results/stress-test.jtl and:
- Show me the top 5 slowest endpoints
- Identify all endpoints with error rates above 5%
- Give me recommendations for improving performance
- Show the 95th percentile response times

Distributed Testing

1. Create a test plan for https://api.example.com with 500 threads
2. Execute it as a distributed test across servers 192.168.1.10, 192.168.1.11, and 192.168.1.12
3. Analyze the combined results

🏗️ Project Structure

jmeter-mcp-server-ts/
├── src/
│   ├── index.ts          # Main MCP server
│   ├── types.ts          # TypeScript type definitions
│   ├── executor.ts       # JMeter test execution
│   ├── analyzer.ts       # Results analysis engine
│   └── builder.ts        # Test plan generation
├── dist/                 # Compiled JavaScript (generated)
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── .env.example          # Environment template
└── README.md            # This file

🔍 Analysis Capabilities

The analyzer provides deep insights into your test results:

Performance Metrics

• Total requests and success rate
• Response time statistics (avg, median, min, max)
• Percentiles (90th, 95th, 99th)
• Throughput (requests/second)
• Bandwidth usage (sent/received)
• Latency and connection time

Bottleneck Detection

• Slow Endpoints: Identifies endpoints with high response times
• High Error Rates: Flags endpoints with frequent failures
• High Latency: Detects network or processing delays
• Severity Levels: Critical, High, Medium, Low

Error Analysis

• Groups errors by response code and message
• Shows affected endpoints per error type
• Calculates error percentages
• Identifies error patterns

Recommendations

AI-powered suggestions for:

• Database optimization
• Caching strategies
• Server capacity planning
• Network configuration
• Load balancing
• Error handling improvements

🛠️ Development

Build

npm run build

Watch Mode

npm run watch

Clean

npm run clean

🐛 Troubleshooting

JMeter Not Found

Error: JMETER_HOME environment variable is not set

Solution: Set JMETER_HOME in your .env file or system environment.

Permission Errors (Linux/Mac)

chmod +x /path/to/jmeter/bin/jmeter

Node Version Issues

Ensure Node.js 18+ is installed:

node --version

Build Errors

Clear and reinstall:

npm run clean
rm -rf node_modules
npm install
npm run build

📝 Configuration

Environment Variables

• JMETER_HOME: Path to JMeter installation (required)
• JMETER_BIN: Path to JMeter binary (optional, auto-detected)
• JMETER_JAVA_OPTS: Java options for JMeter (optional)

JMeter Properties

Properties can be set via the set_jmeter_property tool or directly in:

• jmeter.properties: Main configuration
• user.properties: User-specific settings

🤝 Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

📄 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

• Built on Model Context Protocol by Anthropic
• Powered by Apache JMeter
• Inspired by the original Python implementation

📧 Support

For issues and questions:

• GitHub Issues: Report a bug
• Documentation: Check this README
• JMeter Docs: jmeter.apache.org

🌟 Features Coming Soon

• [ ] GraphQL test plan creation
• [ ] WebSocket testing support
• [ ] Advanced visualization exports
• [ ] CI/CD pipeline integration
• [ ] Performance regression detection
• [ ] Custom plugin support

---

** Enjoy Testing ❤️ by Vj369 **

⭐ Star this repo if you find it useful!