jmeter-mcp-server

Apache JMeter のテストプランを、GUI を開かずに構築・保守・実行・レポート読み取りを行うための stdio MCP サーバーです。

MCP 対応クライアント（Claude Code、Claude Desktop など）をこのサーバーに向けると、テストプランを要素単位で組み立て、実際の非 GUI の JMeter 実行をバックグラウンドで開始し、集計されたレイテンシ/エラー統計を読み戻すことができます。すべて型付きツール呼び出しを通じて行われ、JMeter のツリービューをクリックして操作する必要はありません。

なぜこれに MCP サーバーなのか

LLM はすでに .jmx ファイルをゼロから書くことができます。ただの XML だからです。問題は、JMeter の .jmx 形式が hashTree 構造であり、壊れやすく、微妙に間違いやすい詳細が多数あることです。要素ごとの正確な guiclass/testclass のペア、GUI ラベルと必ずしも一致しないプロパティ名（ThreadGroup.num_threads は intProp ではなく stringProp です。アサーションのマッチタイプは整数の ビットマスク です）、そしてすべての要素とその兄弟 <hashTree> との厳密な親子ペアリング。これらのどれも自己検証的ではありません。わずかに間違ったビットマスクでも、有効でロード可能な XML が生成され、ただ静かに間違った動作をします（発火しないアサーション、出力のないリスナー）。毎回メモリからこれらすべてを再導出することは、毎回同じ間違いを再リスクすることを意味します。

このサーバーはその知識を、実際の JMeter インストールに対して検証されたシリアライザーに一度だけエンコードし、型付きツールとして公開します。そこから得られる具体的な利点は次のとおりです。

• 固定されたテスト済みコードパスによる正確性。 すべての add_http_sampler 呼び出しは同じ検証済みシリアライザーを通ります。LLM が毎回メモリから XML を再生成して、ドリフトや微妙に間違ったプロパティが発生する可能性があるのとは対照的です。

• 安価なインクリメンタル編集。 テストプランは安定したノード ID を持つ小さな JSON ツリーとして保存されます。アサーションを 1 つ追加するのは、parentId を参照する単一のツール呼び出しです。変更を挿入する場所を把握するために .jmx ファイル全体を読み取って書き換える必要はありません。6 要素のプランでの簡単な比較では、JSON ツリーは ~280 トークンでしたが、同等の .jmx XML（guiclass/testclass のペアとリスナーごとの完全な saveConfig ブロックを繰り返す）は ~1,580 トークンでした。そして、この差はプランが大きくなるにつれて広がるだけです。JSON ツリーの編集は、プラン全体がどれだけ大きくても 1 つの小さなツール呼び出し で済むからです。

• 生のサンプルではなく集計結果。 get_execution_report は JTL 出力を解析し、計算された統計（件数、エラー率、平均/最小/最大/中央値、p90/p95/p99、スループット、KB/秒）を返します。クライアントが手動で平均を計算するためのすべてのサンプル行のダンプではありません。

• 真の非同期実行モデル。 execute_test_plan は JMeter をバックグラウンドで起動し、executionId をすぐに返します。get_execution_status / get_execution_report がそれをポーリングします。長時間実行される負荷テストは、単一のリクエスト/レスポンスを待って何かをブロックすることはありません。

生成された .jmx は JMeter 自体が書き出すのと同じ形式に従っているため、視覚的に確認したい場合や UI を好む人に引き渡したい場合に、いつでも実際の JMeter GUI で開くことができます。

Related MCP server: JMeter MCP Server

テストプランの表現方法

各プランは XML テキストではなく JSON ツリー（{id, type, props, children[]}）として保存されます。すべてのオーサリングツールは、指定された parentId の下に子を追加することでこのツリーを変更し、ツリーは実行時にのみ実際の .jmx ファイルにシリアライズされます。これにより、インクリメンタル編集が安価になり、扱いにくい XML スキーマの知識がすべてのツールに分散するのではなく、1 か所（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 はシェルプロファイル（.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