🚀 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

2. Install Dependencies

3. Configure Environment

Create a .env file:

Edit .env and set your JMeter path:

4. Build

🚀 Usage

With Claude Desktop

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

With Cursor / Windsurf

Add to your MCP settings:

🔨 Available Tools

1. validate_jmeter

Validate JMeter installation and get version info.

Example:

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:

3. launch_jmeter_gui

Launch JMeter GUI for test development.

Example:

4. generate_html_report

Generate HTML dashboard from existing results.

Parameters:

• resultsFile: Path to .jtl file

• outputDir: Directory for HTML report

Example:

5. analyze_test_results

Comprehensive analysis of test results.

Example:

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:

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:

8. list_jmeter_plugins

List all installed JMeter plugins.

Example:

9. get_jmeter_properties

Get JMeter configuration properties.

Example:

10. set_jmeter_property

Set a JMeter property.

Parameters:

• key: Property name

• value: Property value

Example:

📊 Example Workflows

Basic Load Test

Advanced Analysis

Distributed Testing

🏗️ Project Structure

🔍 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

Watch Mode

Clean

🐛 Troubleshooting

JMeter Not Found

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

Permission Errors (Linux/Mac)

Node Version Issues

Ensure Node.js 18+ is installed:

Build Errors

Clear and reinstall:

📝 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!