jaeger-mcp

Jaeger 분산 추적을 위한 MCP 서버입니다. Claude(또는 모든 MCP 지원 에이전트)에게 추적 데이터에 대한 읽기 액세스 권한을 부여하여 대화를 떠나지 않고도 추적 검색, 스팬 검사, 서비스 종속성 매핑을 수행할 수 있습니다.

왜 또 다른 Jaeger MCP인가요?

기존 Jaeger 통합은 실행 중인 UI나 사용자 지정 스크립트가 필요합니다. 이 서버는 다음과 같은 특징이 있습니다:

• stdio를 통해 표준 Model Context Protocol을 사용하므로 Claude Desktop, Claude Code, Cursor 및 모든 MCP 클라이언트와 호환됩니다.

• 읽기 전용: 5개의 도구 모두 readOnlyHint: true를 포함하고 있어 추적 데이터를 수정할 위험이 전혀 없습니다.

• 이중 채널 출력: 프로그래밍 방식으로 사용할 수 있는 구조화된 JSON(structuredContent)과 사람이 읽을 수 있는 Markdown(content)을 모두 반환합니다.

• 실행 가능한 오류 메시지: 수정해야 할 정확한 환경 변수를 명시하고 다음 단계를 제안합니다.

• 인증 지원: Bearer 토큰, HTTP Basic 인증 또는 인증 없음(내부 배포 시 일반적)을 지원합니다.

도구

설치

pip install jaeger-mcp

또는 설치 없이 직접 실행:

uvx jaeger-mcp

구성

모든 구성은 환경 변수를 통해 이루어집니다:

.env.example을 .env로 복사하고 값을 입력하세요.

Claude Desktop / Claude Code 설정

MCP 구성(claude_desktop_config.json 또는 .claude/mcp.json)에 추가하세요:

{
  "mcpServers": {
    "jaeger": {
      "command": "jaeger-mcp",
      "env": {
        "JAEGER_URL": "https://jaeger.example.com",
        "JAEGER_TOKEN": "your-token-here"
      }
    }
  }
}

또는 uvx 사용 (설치 불필요):

{
  "mcpServers": {
    "jaeger": {
      "command": "uvx",
      "args": ["jaeger-mcp"],
      "env": {
        "JAEGER_URL": "https://jaeger.example.com"
      }
    }
  }
}

Docker

docker run --rm -e JAEGER_URL=https://jaeger.example.com jaeger-mcp

예시 쿼리

구성이 완료되면 Claude에게 다음과 같이 물어보세요:

• "Jaeger가 알고 있는 서비스는 무엇인가요?"

• "지난 1시간 동안 order-service에서 발생한 HTTP 500 오류가 있는 추적을 찾아줘"

• "GET /checkout에 대한 가장 느린 추적(2초 이상)을 보여줘"

• "추적 abcdef1234567890에서 오류가 발생한 원인은 무엇인가요?"

• "지난 7일간의 서비스 종속성 그래프를 매핑해줘"

• "어떤 서비스가 postgres를 가장 자주 호출하나요?"

도구 사용 가이드

jaeger_list_services

Jaeger가 확인한 모든 서비스 이름을 반환합니다. 어떤 서비스가 계측되었는지 모를 때 여기서 시작하세요. 출력은 500개 서비스로 제한되며 잘림 알림이 포함됩니다.

jaeger_list_operations

특정 서비스에 대한 모든 작업 이름(예: HTTP 경로 이름, gRPC 메서드 이름)을 반환합니다. jaeger_search_traces를 필터링하기 전에 유효한 작업 이름을 찾는 데 사용하세요.

jaeger_search_traces

주요 검색 도구입니다. 필터:

• service (필수) — jaeger_list_services에서 가져온 서비스 이름

• operation — 특정 엔드포인트로 좁히기

• tags — 태그 필터의 JSON 문자열 (예: {"http.status_code":"500"} 또는 {"error":"true"})

• start / end — UTC 마이크로초 단위의 시간 범위

• min_duration / max_duration — "100ms", "1.5s", "2m"와 같은 지속 시간 문자열

• limit — 기본값 20, 최대 1500

trace_id, duration_us, span_count, service_count, root_operation, errors_count가 포함된 추적 요약을 반환합니다.

jaeger_get_trace

전체 추적 세부 정보입니다. trace_id(16-32자 16진수 문자열)를 입력받아 다음을 반환합니다:

• 태그, 서비스 이름, 부모/자식 관계가 포함된 모든 스팬

• 서비스별 통계(스팬 수, 총 지속 시간, 오류 수)

• 실행 트리(각 노드는 자식 스팬 ID를 나열함)

오류 스팬은 tags["error"] = "true"로 식별됩니다.

jaeger_get_dependencies

서비스 토폴로지 그래프입니다. call_count가 포함된 방향성 에지 (부모 → 자식)를 반환합니다. lookback_hours(기본값 24, 최대 720)를 사용하여 기간을 제어하세요.

성능 특성

• 모든 도구는 연결 풀링이 포함된 단일 지속적 requests.Session을 사용합니다.

• 세션은 환경 프록시를 우회하기 위해 trust_env = False로 설정됩니다(Jaeger는 일반적으로 내부 서비스임).

• 요청은 30초 후에 시간 초과됩니다.

• jaeger_search_traces는 limit을 Jaeger에 직접 전달하므로 필요한 것보다 많은 추적을 요청하지 마세요.

• jaeger_get_trace는 한 번의 호출로 전체 추적을 가져오므로 대규모 추적(수천 개의 스팬)은 느릴 수 있습니다.

• jaeger_get_dependencies는 전체 조회 기간에 걸쳐 집계하므로, 바쁜 클러스터에서는 긴 기간을 조회할 경우 느릴 수 있습니다.

개발

git clone https://github.com/mshegolev/jaeger-mcp
cd jaeger-mcp
pip install -e '.[dev]'
pytest tests/ -v
ruff check src tests
ruff format src tests

라이선스

MIT — LICENSE를 참조하세요.