jmeter-mcp-server

Ein stdio-MCP-Server zum Erstellen, Pflegen, Ausführen und Lesen von Berichten für Apache JMeter-Testpläne – ohne die GUI zu öffnen.

Richten Sie einen MCP-fähigen Client (Claude Code, Claude Desktop usw.) auf diesen Server aus, und er kann einen Testplan Element für Element zusammensetzen, einen echten JMeter-Lauf ohne GUI im Hintergrund starten und aggregierte Latenz-/Fehlerstatistiken zurücklesen – alles über typisierte Tool-Aufrufe, statt durch die Baumansicht von JMeter zu klicken.

Warum ein MCP-Server genau dafür

Ein LLM kann bereits eine .jmx-Datei von Grund auf schreiben – es ist schließlich nur XML. Das Problem ist, dass das .jmx-Format von JMeter eine hashTree-Struktur ist, die eine Menge fragiler Details enthält, die man leicht subtil falsch hinbekommt: exakte guiclass/testclass-Paare pro Element, Eigenschaftsnamen, die nicht immer zur GUI-Beschriftung passen (ThreadGroup.num_threads ist eine stringProp, keine intProp; Assertion-Match-Typen sind eine ganzzahlige Bitmaske), sowie eine strikte Eltern/Kind-Paarung zwischen jedem Element und seinem Geschwister-<hashTree>. Nichts davon ist selbstprüfend – eine leicht falsche Bitmaske erzeugt trotzdem gültiges, ladbares XML, das nur stillschweigend das Falsche tut (eine Assertion, die nie zuschlägt, ein Listener ohne Ausgabe). Das alles bei jeder Anfrage aus dem Gedächtnis neu herzuleiten bedeutet, jedes Mal dieselben Fehler erneut zu riskieren.

Dieser Server kodiert dieses Wissen genau einmal, in einem Serializer, der gegen eine echte JMeter-Installation erprobt wurde, und stellt es als typisierte Tools bereit. Die konkreten Vorteile daraus:

• Korrektheit durch einen festen, getesteten Codepfad. Jeder add_http_sampler-Aufruf durchläuft denselben verifizierten Serializer, statt dass ein LLM jedes Mal XML aus dem Gedächtnis neu generiert, mit dem Risiko von Abweichungen oder einer subtil falschen Eigenschaft.

• Kostengünstige inkrementelle Änderungen. Ein Testplan wird als kleiner JSON-Baum mit stabilen Knoten-IDs gespeichert. Eine weitere Assertion hinzuzufügen ist ein einzelner Tool-Aufruf, der eine parentId referenziert – nicht das Lesen und Neuschreiben einer gesamten .jmx-Datei, um herauszufinden, wo eine Änderung eingefügt werden muss. In einem schnellen Side-by-Side-Vergleich bei einem Plan mit 6 Elementen kam der JSON-Baum auf ~280 Tokens gegenüber ~1.580 Tokens für das äquivalente .jmx-XML (das guiclass/testclass-Paare und einen vollständigen saveConfig-Block pro Listener wiederholt) – und diese Lücke wird nur größer, je größer ein Plan wird, denn das Bearbeiten des JSON-Baums kostet einen kleinen Tool-Aufruf, egal wie groß der Plan insgesamt bereits ist.

• Aggregierte Ergebnisse, keine Roh-Samples. get_execution_report parst die JTL-Ausgabe und gibt berechnete Statistiken zurück (Anzahl, Fehler-%, Ø/Min/Max/Median, p90/p95/p99, Durchsatz, KB/s) – keinen Dump jeder Sample-Zeile, den der Client von Hand mitteln müsste.

• Ein echtes asynchrones Ausführungsmodell. execute_test_plan startet JMeter im Hintergrund und kehrt sofort mit einer executionId zurück; get_execution_status / get_execution_report fragen sie ab. Langlaufende Lasttests blockieren nichts, das auf eine einzelne Anfrage/Antwort wartet.

Das erzeugte .jmx folgt demselben Format, das JMeter selbst schreibt, sodass es jederzeit in der echten JMeter-GUI geöffnet werden kann, wenn Sie es sich visuell ansehen oder an jemanden übergeben möchten, der die UI bevorzugt.

Related MCP server: JMeter MCP Server

Wie ein Testplan repräsentiert wird

Jeder Plan wird als JSON-Baum ({id, type, props, children[]}) gespeichert, nicht als XML-Text. Alle Authoring-Tools verändern diesen Baum, indem sie ein Kind unter einer angegebenen parentId anhängen, und der Baum wird erst zur Ausführungszeit in eine echte .jmx-Datei serialisiert. Genau das macht inkrementelle Änderungen kostengünstig und hält das knifflige XML-Schema-Wissen an einem Ort (src/jmx/serializer.ts), statt es über alle Tools zu verteilen.

Tools

Erstellung (jedes gibt die id des neuen Knotens zurück, die als parentId für das verwendet wird, was Sie als Nächstes darunter anhängt):

Inspektion:

Ausführung & Berichte (asynchron – ein Lauf findet im Hintergrund statt):

Beispiel-Workflow

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

Voraussetzungen

• Node.js 18+

• JMeter lokal installiert, wobei die Umgebungsvariable JMETER_HOME auf das Installationsverzeichnis zeigt (dasjenige, das bin/jmeter enthält). Unter macOS via Homebrew legt brew install jmeter es unter /opt/homebrew/opt/jmeter/libexec ab.

Hinzufügen dieses Servers zu Claude Code

Via npx (empfohlen – auf npm veröffentlicht)

Kein Klonen oder Bauen erforderlich; npx lädt die veröffentlichte Version und führt sie direkt aus:

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

Passen Sie den JMETER_HOME-Pfad an den Ort an, an dem JMeter auf Ihrem Rechner installiert ist. Optional können Sie auch JMETER_MCP_WORKSPACE setzen (siehe unten), wenn Pläne und Ausführungen nicht am Standardort gespeichert werden sollen.

Der Standard-Scope ist local (nur dieses Projektverzeichnis). Um ihn in allen Projekten verfügbar zu machen, fügen Sie -s user hinzu:

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

Bestätigen Sie, dass er registriert wurde und antwortet:

claude mcp list

Aus einem lokalen Klon (Entwicklung)

Wenn Sie am Code dieses Repositorys arbeiten, anstatt das veröffentlichte Paket zu verwenden, zeigen Sie direkt auf das gebaute 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

Fügen Sie dies zu ~/Library/Application Support/Claude/claude_desktop_config.json hinzu:

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

Hinweis: Anders als eine im Terminal gestartete App erbt Claude Desktop keine Umgebungsvariablen, die in Ihrem Shell-Profil (.zshrc usw.) exportiert wurden – nur echte systemweite Umgebungsvariablen. Setzen Sie JMETER_HOME immer explizit im env-Block oben, statt sich darauf zu verlassen, dass es auf Ihrem Rechner bereits „gesetzt“ ist.

Umgebungsvariablen

Workspace-Layout

<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

Umfang der v1

Noch nicht unterstützt (Kandidaten für eine zukünftige Version): Bearbeiten/Entfernen vorhandener Elemente, Importieren einer extern erstellten .jmx, Generieren des HTML-Dashboard-Berichts (-e -o), weitere Sampler-/Assertion-/Extractor-Typen, CSV Data Set Config, verteilte Ausführung.

Lizenz

MIT