JMeter MCP

English

文档导航：配置说明 | 工具说明 | Configuration | Tools

JMeter MCP 是一个基于 stdio 的 MCP Server，用于根据结构化接口信息生成和维护 JMeter .jmx 中的 HTTP 请求组件。

它适用于 Codex、Cursor 以及其他支持 MCP 的 AI 客户端。AI 只需要提供项目名、接口路径、HTTP 方法、参数名列表以及是否需要签名；MCP 会根据项目配置自动完成 JMX 写入、请求体生成和 JMeter 运行时签名。

功能特性

• 生成 GenericController 和 HTTPSamplerProxy XML 片段。
• 在配置的 JMeter 线程组中新增或更新基础请求组件。
• 查询和列出现有可复用请求组件。
• 基于基础组件生成场景线程组。
• 根据参数名生成 JSON Raw Body 或 form-data 请求参数。
• 使用 JMeter 内置 __digest 在运行时计算签名字段。

安装与接入

在 MCP 客户端中可以直接通过 npm 包启动：

{
  "mcpServers": {
    "jmeter-mcp": {
      "command": "npx",
      "args": ["-y", "@chenyingxian/jmeter-mcp"],
      "env": {
        "JMETER_MCP_CONFIG_PATH": "D:\\jmeter\\jmeter-mcp.config.json"
      }
    }
  }
}

本地开发命令：

npm install
npm run build
npm start

项目配置

创建一个 JSON 配置文件，并通过 JMETER_MCP_CONFIG_PATH 指向它。

{
  "projects": {
    "example-api-project": {
      "jmx_dir": "D:\\jmeter\\plans",
      "jmx_file": "example-api-project.jmx",
      "sign_algorithm": "key_equals_value",
      "body_type": "json",
      "thread_group_testname": "基础请求组件",
      "scenario_thread_group_testname": "场景测试"
    }
  }
}

支持的 sign_algorithm：

• key_equals_value：签名源字符串按 key=value 拼接。
• key_value：签名源字符串按 keyvalue 拼接。

支持的 body_type：

• json：根据 parameter_names 生成 Raw JSON 请求体。
• form_data：根据 parameter_names 生成 JMeter 表单参数。

常用工具

• jmeter_list_project_config：检查当前加载的项目配置。
• jmeter_list_basic_request_components：列出可复用的基础请求组件。
• jmeter_query_basic_request_component：检查指定组件是否已经存在。
• jmeter_generate_controller_fragment：只生成 XML，不写入 JMX 文件。
• jmeter_upsert_basic_request_component：新增或替换基础请求组件。
• jmeter_upsert_scenario_thread_group：创建或更新单个场景控制器。
• jmeter_upsert_scenario_suite_thread_group：创建或更新场景套件线程组。

请求示例

{
  "project": "example-api-project",
  "match_by": "api_path",
  "match_value": "/api/example",
  "controller_name": "Example API",
  "need_sign": true,
  "doc_url": "https://docs.example.com/api/example",
  "steps": [
    {
      "http_sampler": {
        "testname": "Example API",
        "method": "POST",
        "path": "/api/example",
        "parameter_names": ["deviceId", "channel"]
      }
    }
  ]
}

注意事项

• 不要传真实参数值，只传参数名或 JSON 路径。
• 不要在 parameter_names 中传 sign 或 secret_key。
• 协议、域名、端口、签名密钥建议放在 JMeter 变量或项目级 JMeter 配置中。
• 详细配置见 CONFIG.zh-CN.md，完整工具行为见 MCP_TOOLS.zh-CN.md。