JMeter MCP Server

Instructions

Implementation Reference

• jmeter_server.py:121-121 (registration)

  The @mcp.tool() decorator registers the 'execute_jmeter_test' function as an MCP tool.

  @mcp.tool()

• jmeter_server.py:122-130 (handler)

  The handler function implementing the tool logic. It accepts test_file, gui_mode, and properties parameters and delegates execution to the run_jmeter helper function.

  async def execute_jmeter_test(test_file: str, gui_mode: bool = False, properties: dict = None) -> str:
      """Execute a JMeter test.
  
      Args:
          test_file: Path to the JMeter test file (.jmx)
          gui_mode: Whether to run in GUI mode (default: False)
          properties: Dictionary of JMeter properties to pass with -J (default: None)
      """
      return await run_jmeter(test_file, non_gui=not gui_mode, properties=properties)  # Run in non-GUI mode by default

• jmeter_server.py:25-120 (helper)

  The run_jmeter helper function contains the core logic for executing JMeter tests using subprocess, handling both GUI and non-GUI modes, properties, report generation, and error handling.

  async def run_jmeter(test_file: str, non_gui: bool = True, properties: dict = None, generate_report: bool = False, report_output_dir: str = None, log_file: str = None) -> str:
      """Run a JMeter test.
  
      Args:
          test_file: Path to the JMeter test file (.jmx)
          non_gui: Run in non-GUI mode (default: True)
          properties: Dictionary of JMeter properties to pass with -J (default: None)
          generate_report: Whether to generate report dashboard after load test (default: False)
          report_output_dir: Output folder for report dashboard (default: None)
          log_file: Name of JTL file to log sample results to (default: None)
  
      Returns:
          str: JMeter execution output
      """
      try:
          # Convert to absolute path
          test_file_path = Path(test_file).resolve()
          
          # Validate file exists and is a .jmx file
          if not test_file_path.exists():
              return f"Error: Test file not found: {test_file}"
          if not test_file_path.suffix == '.jmx':
              return f"Error: Invalid file type. Expected .jmx file: {test_file}"
  
          # Get JMeter binary path from environment
          jmeter_bin = os.getenv('JMETER_BIN', 'jmeter')
          java_opts = os.getenv('JMETER_JAVA_OPTS', '')
  
          # Log the JMeter binary path and Java options
          logger.info(f"JMeter binary path: {jmeter_bin}")
          logger.debug(f"Java options: {java_opts}")
  
          # Build command
          cmd = [str(Path(jmeter_bin).resolve())]
          
          if non_gui:
              cmd.extend(['-n'])
          cmd.extend(['-t', str(test_file_path)])
          
          # Add JMeter properties if provided∑
          if properties:
              for prop_name, prop_value in properties.items():
                  cmd.extend([f'-J{prop_name}={prop_value}'])
                  logger.debug(f"Adding property: -J{prop_name}={prop_value}")
          
          # Add report generation options if requested
          if generate_report and non_gui:
              if log_file is None:
                  # Generate unique log file name if not specified
                  unique_id = generate_unique_id()
                  log_file = f"{test_file_path.stem}_{unique_id}_results.jtl"
                  logger.debug(f"Using generated unique log file: {log_file}")
              
              cmd.extend(['-l', log_file])
              cmd.extend(['-e'])
              
              # Always ensure report_output_dir is unique
              unique_id = unique_id if 'unique_id' in locals() else generate_unique_id()
              
              if report_output_dir:
                  # Append unique identifier to user-provided report directory
                  original_dir = report_output_dir
                  report_output_dir = f"{original_dir}_{unique_id}"
                  logger.debug(f"Making user-provided report directory unique: {original_dir} -> {report_output_dir}")
              else:
                  # Generate unique report output directory if not specified
                  report_output_dir = f"{test_file_path.stem}_{unique_id}_report"
                  logger.debug(f"Using generated unique report output directory: {report_output_dir}")
                  
              cmd.extend(['-o', report_output_dir])
  
          # Log the full command for debugging
          logger.debug(f"Executing command: {' '.join(cmd)}")
          
          if non_gui:
              # For non-GUI mode, capture output
              result = subprocess.run(cmd, capture_output=True, text=True)
              
              # Log output for debugging
              logger.debug("Command output:")
              logger.debug(f"Return code: {result.returncode}")
              logger.debug(f"Stdout: {result.stdout}")
              logger.debug(f"Stderr: {result.stderr}")
  
              if result.returncode != 0:
                  return f"Error executing JMeter test:\n{result.stderr}"
              
              return result.stdout
          else:
              # For GUI mode, start process without capturing output
              subprocess.Popen(cmd)
              return "JMeter GUI launched successfully"
  
      except Exception as e:
          return f"Unexpected error: {str(e)}"