jmeter-mcp-server

GUI를 열지 않고 Apache JMeter 테스트 플랜을 빌드하고, 유지 관리하고, 실행하고, 리포트를 읽기 위한 stdio MCP 서버입니다 — GUI를 열지 않고요.

MCP를 지원하는 클라이언트(Claude Code, Claude Desktop 등)를 이 서버에 연결하면, JMeter의 트리 뷰를 클릭하는 대신 타입이 지정된 도구 호출을 통해 테스트 플랜을 요소 단위로 구성하고, 백그라운드에서 실제 non-GUI JMeter 실행을 시작하고, 집계된 지연 시간/오류 통계를 읽어 올 수 있습니다.

왜 하필 MCP 서버인가

LLM은 이미 .jmx 파일을 처음부터 작성할 수 있습니다. 그저 XML일 뿐이니까요. 문제는 JMeter의 .jmx 형식이 hashTree 구조이며, 깨지기 쉽고 미묘하게 틀리기 쉬운 세부 사항이 많다는 점입니다. 요소별 정확한 guiclass/testclass 쌍, GUI 라벨과 항상 일치하지 않는 속성 이름(ThreadGroup.num_threads는 intProp이 아니라 stringProp이며, Assertion 매치 유형은 정수 비트마스크입니다), 그리고 모든 요소와 그 형제 <hashTree> 사이의 엄격한 부모/자식 페어링이 모두 그렇습니다. 그 어떤 것도 자체적으로 검증되지 않습니다. 약간 잘못된 비트마스크도 여전히 유효하고 로드 가능한 XML을 만들어 내며, 조용히 잘못된 동작만 할 뿐입니다(결코 트리거되지 않는 Assertion, 출력이 없는 리스너). 요청할 때마다 이 모든 것을 기억에서 다시 유도한다는 것은 매번 같은 실수를 다시 감수하는 것입니다.

이 서버는 그 지식을 실제 JMeter 설치 환경에서 검증된 serializer에 정확히 한 번만 인코딩하고, 이를 타입이 지정된 도구로 노출합니다. 그 결과 얻을 수 있는 구체적인 이점은 다음과 같습니다.

• 고정되고 테스트된 코드 경로를 통한 정확성. 모든 add_http_sampler 호출은 동일한 검증된 serializer를 거칩니다. LLM이 매번 기억에서 XML을 재생성해 드리프트되거나 미묘하게 잘못된 속성이 생길 가능성이 있는 것과는 대조적입니다.

• 저렴한 증분 편집. 테스트 플랜은 안정적인 노드 id를 가진 작은 JSON 트리로 저장됩니다. Assertion 하나를 추가하는 것은 parentId를 참조하는 단일 도구 호출에 불과합니다. 변경을 끼워 넣을 위치를 찾기 위해 전체 .jmx 파일을 읽고 다시 쓸 필요가 없습니다. 6개 요소 플랜을 빠르게 비교해 보면 JSON 트리는 ~280토큰인 반면, 동등한 .jmx XML(리스너마다 guiclass/testclass 쌍과 전체 saveConfig 블록을 반복하는)은 ~1,580토큰이었습니다. 그리고 플랜이 커질수록 그 격차는 더욱 벌어집니다. 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

테스트 플랜이 표현되는 방식

각 플랜은 XML 텍스트가 아닌 JSON 트리({id, type, props, children[]})로 저장됩니다. 모든 작성 도구는 주어진 parentId 아래에 자식을 추가하는 방식으로 이 트리를 변경하며, 트리는 실행 시점에만 실제 .jmx 파일로 직렬화됩니다. 이것이 증분 편집을 저렴하게 만들고, 까다로운 XML 스키마 지식을 모든 도구에 분산하지 않고 한곳(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), 기타 샘플러/Assertion/추출기 유형, CSV Data Set Config, 분산 실행.

라이선스

MIT