prometheus-mcp

PyPI version Python versions License: MIT Tests

Prometheus 메트릭 및 관측 가능성을 위한 MCP 서버입니다. Claude(또는 MCP 지원 에이전트)에게 Prometheus 인스턴스에 대한 읽기 권한을 부여하여, 대화를 떠나지 않고도 PromQL로 메트릭을 쿼리하고, 활성 알림을 검사하며, 스크랩 대상을 탐색할 수 있습니다.

왜 또 다른 Prometheus MCP인가요?

기존 Prometheus 통합은 사용자 지정 스크립트나 직접적인 API 지식이 필요합니다. 이 서버는 다음과 같은 특징이 있습니다:

stdio를 통해 표준 Model Context Protocol을 사용하므로 Claude Desktop, Claude Code, Cursor 및 모든 MCP 클라이언트와 작동합니다.
읽기 전용: 5개의 도구 모두 readOnlyHint: true를 포함하고 있어 Prometheus 데이터를 수정할 위험이 전혀 없습니다.
이중 채널 출력: 프로그래밍 방식으로 사용할 수 있는 구조화된 JSON(structuredContent)과 사람이 읽을 수 있는 Markdown(content)을 모두 반환합니다.
실행 가능한 오류 메시지: 수정해야 할 정확한 환경 변수를 명시하고 다음 단계를 제안합니다.
인증 지원: Bearer 토큰, HTTP Basic 인증 또는 인증 없음(내부 배포 시 일반적)을 지원합니다.

도구

도구	엔드포인트	설명
`prometheus_list_metrics`	`GET /api/v1/label/__name__/values`	선택적 하위 문자열 필터(최대 500개)를 사용하여 모든 메트릭 이름 나열
`prometheus_query`	`GET /api/v1/query`	즉시 PromQL 쿼리 실행
`prometheus_query_range`	`GET /api/v1/query_range`	시계열을 반환하는 PromQL 범위 쿼리 실행
`prometheus_list_alerts`	`GET /api/v1/alerts`	활성 및 보류 중인 알림 나열
`prometheus_list_targets`	`GET /api/v1/targets`	상태 및 작업별로 스크랩 대상 나열

설치

pip install prometheus-mcp

또는 설치 없이 직접 실행:

uvx prometheus-mcp

구성

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

변수	필수	기본값	설명
`PROMETHEUS_URL`	예	—	Prometheus 서버 URL (예: `https://prometheus.example.com`, 끝에 슬래시 없음)
`PROMETHEUS_TOKEN`	아니요	—	Bearer 토큰 (Basic 인증보다 우선)
`PROMETHEUS_USERNAME`	아니요	—	HTTP Basic 인증 사용자 이름
`PROMETHEUS_PASSWORD`	아니요	—	HTTP Basic 인증 비밀번호
`PROMETHEUS_SSL_VERIFY`	아니요	`true`	자체 서명된 인증서의 경우 `false`로 설정

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

Claude Desktop / Claude Code 설정

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

{
  "mcpServers": {
    "prometheus": {
      "command": "prometheus-mcp",
      "env": {
        "PROMETHEUS_URL": "https://prometheus.example.com",
        "PROMETHEUS_TOKEN": "your-token-here"
      }
    }
  }
}

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

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

Docker

docker run --rm -e PROMETHEUS_URL=https://prometheus.example.com prometheus-mcp

쿼리 예시

구성 후 Claude에게 다음과 같이 질문해 보세요:

"Prometheus에 HTTP 요청에 관한 어떤 메트릭이 있나요?"
"결제 서비스의 현재 요청 속도는 얼마인가요?"
"지난 1시간 동안의 CPU 사용량을 5분 해상도로 보여줘"
"현재 발생 중인 알림이 있나요? 심각도는 어떤가요?"
"현재 다운된 스크랩 대상은 무엇이며 그 이유는 무엇인가요?"
"node-exporter 인스턴스가 몇 개나 실행 중인가요?"

도구 사용 가이드

`prometheus_list_metrics`

Prometheus가 알고 있는 모든 메트릭 이름을 반환합니다. 하위 문자열로 필터링하려면 pattern을 사용하세요(대소문자 구분 안 함). 어떤 메트릭을 사용할 수 있는지 모를 때 여기서 시작하세요. 출력은 500개 메트릭으로 제한되며 잘림 알림이 포함됩니다.

`prometheus_query`

즉시 PromQL 표현식을 실행하고 현재 값을 가져옵니다. 결과 유형(벡터/스칼라/행렬/문자열), 샘플 수, 샘플별 레이블 및 값을 반환합니다.

매개변수:

query (필수) — PromQL 표현식 (예: up, rate(http_requests_total[5m]))
time (선택) — RFC3339 또는 Unix 타임스탬프; 기본값은 현재 시간

`prometheus_query_range`

시간 창에 걸쳐 PromQL 표현식을 실행합니다. 일치하는 시계열당 하나의 시리즈를 타임스탬프 값과 함께 반환합니다. 모든 시리즈의 총 데이터 포인트는 5000개로 제한됩니다.

매개변수:

query (필수) — PromQL 표현식
start / end (필수) — RFC3339 또는 Unix 타임스탬프
step (필수) — 15s, 1m, 5m과 같은 해상도

Prometheus는 시리즈당 11,000개 이상의 포인트를 생성하는 단계(HTTP 422)를 거부합니다. 이 경우 단계를 늘리거나 범위를 좁히세요.

참고: Prometheus 범위 API는 브랜치나 커밋별 필터링을 지원하지 않습니다. 필터는 순수하게 PromQL 레이블 매처로 표현됩니다.

`prometheus_list_alerts`

레이블(alertname, severity 포함), 상태, 활성화 시간 및 현재 값을 포함하여 활성/보류 중인 모든 알림을 반환합니다. 상태 요약(발생 중 vs 보류 중 개수)이 포함됩니다.

`prometheus_list_targets`

작업 이름, 인스턴스 주소, 상태(up/down/unknown), 마지막 스크랩 지속 시간(밀리초) 및 오류 메시지가 포함된 스크랩 대상을 반환합니다. 작업별 요약이 포함됩니다. state로 필터링 가능: active(기본값), dropped, any.

성능 특성

모든 도구는 연결 풀링이 포함된 단일 영구 requests.Session을 사용합니다.
세션은 환경 프록시를 우회하기 위해 trust_env = False로 설정됩니다(Prometheus는 일반적으로 내부 서비스임).
요청은 30초 후에 타임아웃됩니다.
prometheus_query_range는 모든 시리즈에 걸쳐 총 5000개 포인트로 출력을 제한합니다. 긴 시간 창의 경우 더 큰 단계를 사용하세요.
prometheus_list_metrics는 필터링 후 최대 500개의 메트릭을 반환합니다.

개발

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

라이선스

MIT — LICENSE를 참조하세요.

mshegolev/prometheus-mcp