jmeter-mcp-server

一个基于 stdio 的 MCP 服务器，用于构建、维护、运行 Apache JMeter 测试计划并读取其报告——无需打开 GUI。

将支持 MCP 的客户端（Claude Code、Claude Desktop 等）指向该服务器后，它就能逐元素地组合测试计划，在后台启动一次真实的非 GUI JMeter 运行，并读回聚合的延迟/错误统计信息——所有这些都通过类型化的工具调用完成，而不是在 JMeter 的树形视图中逐个点击。

为什么专门为此提供一个 MCP 服务器

LLM 已经可以从零编写 .jmx 文件——它不过是 XML。问题在于 JMeter 的 .jmx 格式是一个 hashTree 结构，包含大量脆弱、容易在细微之处出错的细节：每个元素必须配对的 guiclass/testclass、不一定与 GUI 标签一致的属性名（ThreadGroup.num_threads 是 stringProp 而非 intProp；断言匹配类型是一个整数 位掩码），以及每个元素与其兄弟 <hashTree> 之间严格的父子配对。这些都不是自校验的——一个略微错误的位掩码仍然会生成有效、可加载的 XML，但只会悄悄做错事（一个永远不会触发的断言，一个没有输出的监听器）。每次请求都凭记忆重新推导所有这些细节，意味着每次都会重新承担同样的错误风险。

此服务器将这些知识只编码一次，放在一个已经针对真实 JMeter 安装验证过的序列化器中，并以类型化工具的形式暴露出来。由此带来的具体好处：

• 通过固定且经过测试的代码路径保证正确性。 每次 add_http_sampler 调用都会经过同一个经过验证的序列化器，而不是让 LLM 每次凭记忆重新生成 XML，从而避免产生偏差或细微错误的属性。

• 低成本增量编辑。 测试计划以带有稳定节点 id 的小型 JSON 树存储。增加一个断言只需要一次引用 parentId 的工具调用——而不是读取并重写整个 .jmx 文件来找出应该在何处插入变更。在包含 6 个元素的计划的快速对比中，JSON 树约为 280 tokens，而等效的 .jmx XML 约为 1,580 tokens（后者会为每个监听器重复 guiclass/testclass 对和完整的 saveConfig 块）——而且随着测试计划增大，这一差距只会进一步扩大，因为编辑 JSON 树只需 一次小小的工具调用，无论整个计划已经有多大。

• 聚合结果，而非原始样本。 get_execution_report 解析 JTL 输出并返回计算后的统计信息（数量、错误率、平均值/最小值/最大值/中位数、p90/p95/p99、吞吐量、KB/s）——而不是把每个样本行都转储出来，让客户端手动求平均。

• 真正的异步执行模型。 execute_test_plan 在后台启动 JMeter，并立即返回一个 executionId；get_execution_status / get_execution_report 对其进行轮询。长时间运行的负载测试不会因等待单个请求/响应而阻塞任何东西。

生成的 .jmx 采用与 JMeter 自身写入相同的格式，因此如果你想在真实 JMeter GUI 中直观查看，或者把它交给更喜欢 UI 的人，随时都可以打开。

Related MCP server: JMeter MCP Server

测试计划的表示方式

每个测试计划都以 JSON 树（{id, type, props, children[]}）形式存储，而不是 XML 文本。所有创作工具都通过在给定的 parentId 下追加子节点来修改这棵树，并且这棵树只在执行时才被序列化为真正的 .jmx 文件。这正是增量编辑成本低廉的原因，也将繁琐的 XML schema 知识集中在一处（src/jmx/serializer.ts），而不是分散在每个工具中。

工具

创作工具（每个工具都会返回新节点的 id，可用作接下来附加在其下的任何节点的 parentId）：

检查工具：

执行与报告（异步——运行在后台进行）：

示例工作流

create_test_plan            → { planId, rootNodeId }
add_thread_group             (parentId: rootNodeId)  → { nodeId: threadGroupId }
add_http_sampler              (parentId: threadGroupId) → { nodeId: samplerId }
add_response_assertion        (parentId: samplerId)
add_aggregate_report_listener (parentId: threadGroupId)
execute_test_plan             (planId) → { executionId }
get_execution_status           (executionId)   ← poll until "completed"
get_execution_report            (executionId) → aggregated latency/error stats

前提条件

• Node.js 18+

• 本地安装 JMeter，并通过 JMETER_HOME 环境变量指向安装目录（包含 bin/jmeter 的那个目录）。在 macOS 上通过 Homebrew 安装时，brew install jmeter 会将其放在 /opt/homebrew/opt/jmeter/libexec。

将此服务器添加到 Claude Code

通过 npx（推荐——已发布到 npm）

无需克隆或构建；npx 会即时获取并运行已发布的版本：

claude mcp add jmeter \
  -e JMETER_HOME=/opt/homebrew/opt/jmeter/libexec \
  -- npx -y jmeter-mcp-server

将 JMETER_HOME 路径调整为你的机器上 JMeter 的安装位置。如果你希望将测试计划和执行结果存储在其他位置而非默认位置，还可以设置 JMETER_MCP_WORKSPACE（见下文）。

默认作用域为 local（仅当前项目目录）。若要让它对所有项目可用，请添加 -s user：

claude mcp add jmeter -s user \
  -e JMETER_HOME=/opt/homebrew/opt/jmeter/libexec \
  -- npx -y jmeter-mcp-server

确认它已注册并能正常响应：

claude mcp list

从本地克隆（开发）

如果你正在开发此仓库的代码，而不是使用已发布的包，请直接指向构建后的 dist/index.js：

npm install
npm run build
claude mcp add jmeter \
  -e JMETER_HOME=/opt/homebrew/opt/jmeter/libexec \
  -- node /absolute/path/to/jmeter-mcp-server/dist/index.js

Claude Desktop

将此配置添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "jmeter": {
      "command": "npx",
      "args": ["-y", "jmeter-mcp-server"],
      "env": {
        "JMETER_HOME": "/opt/homebrew/opt/jmeter/libexec"
      }
    }
  }
}

注意：与从终端启动的应用不同，Claude Desktop 不会继承你在 shell 配置文件（.zshrc 等）中导出的环境变量——只会继承真正的系统级变量。请始终在上面的 env 块中显式设置 JMETER_HOME，而不要依赖它“已经在你的机器上设置好了”。

环境变量

工作区布局

<workspace>/
  plans/<planId>/plan.json           # JSON tree — source of truth for a plan
  executions/<executionId>/
    generated.jmx                    # serialized at execute_test_plan time
    aggregate-report.jtl             # output of the Aggregate Report listener, if present
    summary-report.jtl               # output of the Summary Report listener, if present
    jmeter.log
    meta.json                        # execution status, pid, timestamps, exit code

v1 范围

尚不支持（未来版本可能支持）：编辑/删除现有元素、导入外部编写的 .jmx、生成 HTML 仪表盘报告（-e -o）、其他采样器/断言/提取器类型、CSV Data Set Config、分布式执行。

许可证

MIT