mcp-victoriametrics

VictoriaMetrics MCP 서버

VictoriaMetrics를 위한 MCP(Model Context Protocol) 서버 구현.

이를 통해 VictoriaMetrics 인스턴스에 대한 접근 권한과 VictoriaMetrics API 및 문서 와의 원활한 통합이 제공됩니다. VictoriaMetrics 인스턴스 관련 모니터링, 관측 및 디버깅 작업을 위한 포괄적인 인터페이스를 제공하고, 엔지니어와 도구를 위한 고급 자동화 및 상호 작용 기능을 활성화할 수 있습니다.

특징

이 MCP 서버를 사용하면 VictoriaMetrics의 거의 모든 읽기 전용 API, 즉 VMUI 에서 사용 가능한 모든 기능을 사용할 수 있습니다.

메트릭 쿼리 및 데이터 탐색(클라이언트가 지원하는 경우 그래프 그리기도 가능)
사용 가능한 메트릭, 레이블, 레이블 값 및 전체 시리즈 나열 및 내보내기
알림 및 녹음 규칙과 알림 분석
VictoriaMetrics 인스턴스의 매개변수 표시
데이터 및 메트릭 사용 통계의 기수 탐색
귀하의 쿼리 분석
재레이블링 규칙, 다운샘플링 및 보존 정책 구성 디버깅

또한 MCP 서버에는 최신 문서가 내장되어 있어 온라인 접속 없이도 검색할 수 있습니다.

사용 가능한 도구와 프롬프트에 대한 자세한 내용은 사용 섹션에서 확인할 수 있습니다.

도구 기능, 문서 검색 기능을 프롬프트에 결합하여 VictoriaMetrics 인스턴스에 대한 훌륭한 사용 시나리오를 만들어낼 수 있습니다. 작동 방식은 Dialog 예제 섹션을 참조하세요. MCP 서버와 응답의 품질은 클라이언트의 성능과 사용 중인 모델의 품질에 따라 크게 달라진다는 점에 유의하세요.

MCP 서버를 다른 관찰성 또는 문서 검색 관련 MCP 서버와 결합하여 더욱 강력한 결과를 얻을 수도 있습니다.

요구 사항

VictoriaMetrics 인스턴스( 단일 노드 또는 클러스터 )
Go 1.24 이상(소스에서 빌드하려는 경우)

설치

가다

지엑스피1

소스 코드

git clone https://github.com/VictoriaMetrics-Community/mcp-victoriametrics.git
cd mcp-victoriametrics
go build -o bin/mcp-victoriametrics ./cmd/mcp-victoriametrics/main.go

# after that add bin/mcp-victoriametrics file to your PATH

바이너리

릴리스 페이지에서 최신 릴리스를 다운로드하고 PATH에 추가하세요.

도커

곧 출시됩니다...

구성

VictoriaMetrics용 MCP 서버는 환경 변수를 통해 구성됩니다.

변하기 쉬운	설명	필수의	기본	허용된 값
`VM_INSTANCE_ENTRYPOINT`	VictoriaMetrics 인스턴스의 URL	예	-	-
`VM_INSTANCE_TYPE`	VictoriaMetrics 인스턴스 유형	예	-	`single` , `cluster`
`VM_INSTANCE_BEARER_TOKEN`	VictoriaMetrics API에 대한 인증 토큰	아니요	-	-
`MCP_SERVER_MODE`	서버 작동 모드	아니요	`stdio`	`stdio` , `sse`
`MCP_SSE_ADDR`	SSE 서버가 수신할 주소	아니요	`localhost:8080`	-

구성 예

# For a single-node instance
export VM_INSTANCE_ENTRYPOINT="http://localhost:8428"
export VM_INSTANCE_TYPE="single"
export VM_INSTANCE_BEARER_TOKEN="your-token"

# For a cluster
export VM_INSTANCE_ENTRYPOINT="https://play.victoriametrics.com"
export VM_INSTANCE_TYPE="cluster"

# Server mode
export MCP_SERVER_MODE="sse"
export MCP_SSE_ADDR="0.0.0.0:8080"

클라이언트 설정

커서

Settings -> Cursor Settings -> MCP -> Add new global MCP server 로 이동하여 다음 구성을 커서 ~/.cursor/mcp.json 파일에 붙여넣습니다.

{
  "mcpServers": {
    "victoriametrics": {
      "command": "/path/to/mcp-victoriametrics",
      "env": {
        "VM_INSTANCE_ENTRYPOINT": "<YOUR_VM_INSTANCE>",
        "VM_INSTANCE_TYPE": "<YOUR_VM_INSTANCE_TYPE>",
        "VM_INSTANCE_BEARER_TOKEN": "<YOUR_VM_BEARER_TOKEN>"
      }
    }
  }
}

자세한 내용은 커서 MCP 문서를 참조하세요.

클로드 데스크탑

Claude Desktop claude_desktop_config.json 파일에 다음을 추가합니다( Settings -> Developer -> Edit config 열면 찾을 수 있습니다).

{
  "mcpServers": {
    "victoriametrics": {
      "command": "/path/to/mcp-victoriametrics",
      "env": {
        "VM_INSTANCE_ENTRYPOINT": "<YOUR_VM_INSTANCE>",
        "VM_INSTANCE_TYPE": "<YOUR_VM_INSTANCE_TYPE>",
        "VM_INSTANCE_BEARER_TOKEN": "<YOUR_VM_BEARER_TOKEN>"
      }
    }
  }
}

자세한 내용은 Claude Desktop MCP 문서를 참조하세요.

클로드 코드

다음 명령을 실행합니다.

claude mcp add victoriametrics -- /path/to/mcp-victoriametrics \
  -e VM_INSTANCE_ENTRYPOINT=<YOUR_VM_INSTANCE> \
  -e VM_INSTANCE_TYPE=<YOUR_VM_INSTANCE_TYPE>
  -e VM_INSTANCE_BEARER_TOKEN=<YOUR_VM_BEARER_TOKEN>

자세한 내용은 Claude Code MCP 문서를 참조하세요.

비주얼 스튜디오 코드

VS Code MCP 구성 파일에 다음을 추가하세요.

{
  "servers": {
    "victoriametrics": {
      "type": "stdio",
      "command": "/path/to/mcp-victoriametrics",
      "env": {
        "VM_INSTANCE_ENTRYPOINT": "<YOUR_VM_INSTANCE>",
        "VM_INSTANCE_TYPE": "<YOUR_VM_INSTANCE_TYPE>",
        "VM_INSTANCE_BEARER_TOKEN": "<YOUR_VM_BEARER_TOKEN>"
      }
    }
  }
}

자세한 내용은 VS Code MCP 문서를 참조하세요.

제드 자의 명칭

Zed 구성 파일에 다음을 추가하세요.

  "context_servers": {
    "victoriametrics": {
      "command": {
        "path": "/path/to/mcp-victoriametrics",
        "args": [],
        "env": {
          "VM_INSTANCE_ENTRYPOINT": "<YOUR_VM_INSTANCE>",
          "VM_INSTANCE_TYPE": "<YOUR_VM_INSTANCE_TYPE>",
          "VM_INSTANCE_BEARER_TOKEN": "<YOUR_VM_BEARER_TOKEN>"
        }
      },
      "settings": {}
    }
  }

자세한 내용은 Zed MCP 문서를 참조하세요.

JetBrains IDE

Settings -> Tools -> AI Assistant -> Model Context Protocol (MCP) 엽니다.
Add (+) 클릭하세요
As JSON 선택
입력 필드에 다음을 입력하세요.

{
  "mcpServers": {
    "victoriametrics": {
      "command": "/path/to/mcp-victoriametrics",
      "env": {
        "VM_INSTANCE_ENTRYPOINT": "<YOUR_VM_INSTANCE>",
        "VM_INSTANCE_TYPE": "<YOUR_VM_INSTANCE_TYPE>",
        "VM_INSTANCE_BEARER_TOKEN": "<YOUR_VM_BEARER_TOKEN>"
      }
    }
  }
}

윈드서핑

Windsurf MCP 구성 파일에 다음을 추가하세요.

{
  "mcpServers": {
    "victoriametrics": {
      "command": "/path/to/mcp-victoriametrics",
      "env": {
        "VM_INSTANCE_ENTRYPOINT": "<YOUR_VM_INSTANCE>",
        "VM_INSTANCE_TYPE": "<YOUR_VM_INSTANCE_TYPE>",
        "VM_INSTANCE_BEARER_TOKEN": "<YOUR_VM_BEARER_TOKEN>"
      }
    }
  }
}

자세한 내용은 Windsurf MCP 문서를 참조하세요.

아마존 베드락

곧 출시됩니다....

바이너리 대신 Docker 사용

곧 출시됩니다...

용법

MCP 서버를 설치 하고 구성한 후에는 원하는 MCP 클라이언트와 함께 사용할 수 있습니다.

다음 문구를 통해 AI 도우미와 대화를 시작할 수 있습니다.

Use MCP VictoriaMetrics in the following answers

하지만 필수는 아닙니다. 질문을 하기만 하면 어시스턴트가 자동으로 도구와 문서를 활용하여 최상의 답변을 제공합니다. Dialog 예시 섹션을 참고하시면 어떤 기능을 사용할 수 있는지 더 자세히 이해하실 수 있습니다.

도구 세트

MCP VictoriaMetrics는 VictoriaMetrics 인스턴스와 상호 작용하기 위한 다양한 도구를 제공합니다.

사용 가능한 도구 목록은 다음과 같습니다.

도구	설명
`query`	PromQL/MetricsQL 쿼리를 즉시 실행합니다.
`query_range`	특정 기간 동안 PromQL/MetricsQL 쿼리 범위 실행
`metrics`	사용 가능한 메트릭 나열
`labels`	사용 가능한 레이블 이름 나열
`label_values`	특정 레이블에 대한 값 나열
`series`	사용 가능한 시계열 목록
`export`	원시 시계열 데이터를 JSON 또는 CSV로 내보내기
`rules`	알림 및 녹음 규칙 보기
`alerts`	현재 알림(발사 및 보류) 보기
`flags`	VictoriaMetrics 인스턴스의 기본이 아닌 플래그 보기
`metric_statistics`	(쿼리에서) 메트릭 사용 통계 가져오기
`active_queries`	현재 실행 중인 쿼리 보기
`top_queries`	가장 빈번하거나 가장 느린 쿼리 보기
`tsdb_status`	TSDB 기수 통계 보기
`tenants`	멀티 테넌트 클러스터 설정에서 사용 가능한 테넌트 나열
`documentation`	내장된 VictoriaMetrics 문서에서 검색
`metric_relabel_debug`	Prometheus 호환 재레이블링 규칙 디버그
`downsampling_filters_debug`	디버그 다운샘플링 구성
`retention_filters_debug`	디버그 보존 필터 구성

프롬프트

서버에는 일반적인 작업에 대한 미리 정의된 프롬프트가 포함되어 있습니다.

현재는 단지 예시일 뿐이며, 프롬프트 라이브러리는 앞으로 추가될 예정입니다.

즉각적인	설명
`unused_metrics`	쿼리되지 않는 메트릭을 찾아 이를 수집하지 못하도록 재레이블 구성을 생성합니다.
`documentation`	특정 주제에 대한 VictoriaMetrics 문서 검색
`rarely_used_metrics_with_high_cardinality`	거의 쿼리되지 않는 높은 카디널리티 메트릭 식별

다운샘플링은 VictoriaMetrics의 엔터프라이즈 기능입니다. 라이선스 파일이 구성된 것을 확인했으므로 현재 라이선스로 다운샘플링을 사용할 수 있습니다.

대화 예제

이는 MCP 서버를 사용하는 Assistant와의 대화의 예일 뿐이며, 작동 방식을 이해하는 데 도움이 될 수 있습니다(하지만 실제로는 Claude Desktop과 공개 플레이그라운드 인스턴스 로 구성된 Victoria Metrics MCP 서버를 사용하는 대화입니다).

귀하 : 내 VM에서 어떤 테넌트를 사용할 수 있나요?
VictoriaMetrics 인스턴스에서 다음 테넌트를 사용할 수 있습니다. 0:0 (기본 테넌트), 1:0 , 10:0 , 100:0 0
귀하 : 지금부터는 기본 테넌트만 사용하세요.
Assistant : 알겠습니다. 이제부터 VictoriaMetrics 인스턴스 관련 모든 작업에 기본 테넌트(0:0)만 사용하겠습니다.
당신 : 우리는 어떤 측정 항목을 가지고 있나요?
Assistant : VictoriaMetrics 인스턴스에는 다양한 메트릭이 있습니다. 이 목록에는 다음과 같은 다양한 시스템 및 구성 요소의 메트릭이 포함됩니다.
- 시스템 메트릭( node_ , machine_ 등)
- Kubernetes 메트릭( kube_ , container_ , apiserver_ 등)
- VictoriaMetrics 특정 메트릭( vm_ , vmagent_ , vmalert_ 등)
- Go 런타임 메트릭( go_ ),
- Prometheus 관련 메트릭( scrape_ , promhttp_ ),
- 다양한 애플리케이션 메트릭( argocd_ , alertmanager_ ).
2,000개 이상의 지표를 포괄적으로 정리한 목록입니다. 더 자세히 살펴보고 싶은 특정 유형의 지표가 있으신가요?
당신 : 좋아요, 이제부터 쿠버네티스 메트릭을 사용해 봅시다. 이 메트릭 중 쿼리되지 않은 메트릭이 무엇인지 알려주세요.
Assistant : 결과를 바탕으로, 쿼리된 적이 없는 Kubernetes 메트릭이 두 개 있는 것을 알 수 있습니다(쿼리 수는 0입니다).
- kube_persistentvolumeclaim_deletion_timestamp - 이 메트릭은 PersistentVolumeClaims가 삭제 표시된 시점에 대한 정보를 제공합니다.
- kube_pod_init_container_status_last_terminated_reason - 이 메트릭은 Pod 내 init 컨테이너가 마지막으로 종료된 이유를 보여줍니다.
이러한 측정항목은 모니터링 및 문제 해결 목적으로 유용할 수 있습니다.
- PVC 삭제 타임스탬프 메트릭은 삭제 패턴을 추적하거나 중단된 PVC를 식별하는 데 도움이 될 수 있습니다.
- init 컨테이너 종료 이유 메트릭은 초기화 컨테이너에서 일반적인 실패 패턴을 식별하는 데 도움이 될 수 있습니다.
이러한 지표가 추적하는 내용에 대해 자세히 설명해 주시겠습니까? 아니면 이를 모니터링하기 위한 유용한 쿼리를 제안해 주시겠습니까?
당신 : 네, 부탁드립니다. 그리고, 이러한 지표 수집을 막기 위해 재레이블링 규칙을 만들어 주실 수 있나요?
Assistant : 쿼리되지 않은 이러한 메트릭을 수집에서 제외하는 재라벨링 구성을 생성하겠습니다. 이렇게 하면 저장 및 처리 오버헤드를 줄이는 데 도움이 됩니다. VictoriaMetrics 스크레이핑 구성에 추가할 수 있는 재라벨링 구성은 다음과 같습니다.
relabel_configs: - action: drop source_labels: [__name__] regex: kube_persistentvolumeclaim_deletion_timestamp|kube_pod_init_container_status_last_terminated_reason
이 구성은 다음을 수행합니다.
1. 각 메트릭의 이름( __name__ 레이블)을 살펴보세요.
2. 지정된 메트릭 중 하나와 일치하는지 확인하세요.
3. 일치하는 메트릭을 삭제하여 수집 및 저장을 방지합니다.
VictoriaMetrics의 스크래퍼로 Prometheus를 사용하는 경우, VictoriaMetrics 구성 파일이나 Prometheus 구성의 관련 스크래핑 작업 구성에 이 설정을 추가할 수 있습니다. 이 재레이블 구성을 구현하기 전에 테스트하려면 메트릭 재레이블 디버그 도구를 사용하여 메트릭에 어떤 영향을 미치는지 확인할 수 있습니다.
귀하 : 예, 실시간 시리즈에서 이 재라벨 구성을 디버깅하여 내 메트릭에 어떤 영향을 미치는지 확인하십시오.
Assistant : 완벽해요! 라벨 재지정 구성이 예상대로 작동합니다.
- 처음 두 테스트 사례는 kube_persistentvolumeclaim_deletion_timestamp 와 kube_pod_init_container_status_last_terminated_reason 메트릭이 모두 올바르게 삭제되었음을 보여줍니다(결과 레이블은 비어 있음 {} ).
- 세 번째 테스트 사례에서는 kube_pod_status_phase 와 같은 다른 메트릭이 보존되고 삭제 규칙의 영향을 받지 않는다는 것을 확인합니다.
VictoriaMetrics 또는 Prometheus 구성에 이 재레이블 구성을 추가하면 사용하지 않는 메트릭 수집을 중단할 수 있습니다. 이렇게 하면 현재 모니터링 기능에 영향을 주지 않고 저장 공간을 절약하고 처리 오버헤드를 줄일 수 있습니다.
당신 : 하지만 저는 VictoriaMetrics 연산자의 vmagent 리소스를 사용하고 있는데, 이 재레이블 구성에 대한 제 에이전트의 사양 일부를 알려주시겠습니까?
Assistant : 맞습니다. VictoriaMetrics Operator와 VMAgent 사용자 지정 리소스를 사용하고 있으므로 구성은 해당 CR에 적합한 형식이어야 합니다. VMAgent 사양에 레이블 재지정 구성을 추가하는 방법은 다음과 같습니다.
apiVersion: operator.victoriametrics.com/v1beta1 kind: VMAgent metadata: name: your-vmagent-name spec: # ... your existing configuration ... # Add this section to configure global metric relabeling inlineRelabelConfig: - action: drop sourceLabels: ["__name__"] regex: kube_persistentvolumeclaim_deletion_timestamp|kube_pod_init_container_status_last_terminated_reason # ... rest of your configuration ...
핵심 포인트:
- VMAgent 사양에서는 인라인 재레이블링 규칙에 대해 inlineRelabelConfig 사용합니다.
- 필드는 sourceLabels 라고 합니다(Prometheus 구성의 source_labels 가 아님)
- 이는 모든 메트릭이 저장되기 전에 적용되는 글로벌 재레이블링입니다.
당신 : 해당 지표를 제거하지 않고 다운샘플링을 사용하여 샘플링 레이트만 낮추기로 했습니다. 현재 제가 가진 다운샘플링 매개변수는 무엇인가요?
보조원 : 현재 다음과 같은 다운샘플링 구성이 있는 것으로 보입니다.
-downsampling.period="7d:1m,30d:5m,180d:30m"
이는 다음을 의미합니다.
- 7일 이상 지난 데이터는 원래 해상도로 보관됩니다.
- 7~30일 전 데이터는 1분 해상도로 다운샘플링됩니다.
- 30~180일 된 데이터는 5분 해상도로 다운샘플링됩니다.
- 180일 이상 된 데이터는 30분 해상도로 다운샘플링됩니다.
이제 쿼리 빈도가 낮은 지표에 대해 특정 다운샘플링 규칙을 추가하려면 다운샘플링 필터 디버그 도구를 사용하여 새 규칙이 어떻게 작동하는지 테스트할 수 있습니다. 특정 지표에 더욱 공격적인 다운샘플링을 적용하는 구성을 테스트해 보겠습니다.
...시리즈를 가져오고 다운샘플링 필터 디버거를 사용합니다...
좋습니다! 이제 테스트가 정상적으로 작동합니다. 현재 구성과 테스트 결과를 바탕으로, VMAgent CR에 대해 쿼리 빈도가 낮은 메트릭에 더욱 적극적인 다운샘플링을 적용하는 다운샘플링 구성을 제안합니다.
apiVersion: operator.victoriametrics.com/v1beta1 kind: VMCluster metadata: name: monitoring-vm-cluster spec: # ... your existing configuration ... # Update the vmstorage section with the new downsampling parameters vmstorage: extraArgs: downsampling.period: - "{__name__=\"kube_persistentvolumeclaim_deletion_timestamp\"}:1d:10m" - "{__name__=\"kube_pod_init_container_status_last_terminated_reason\"}:1d:10m" - "7d:1m" - "30d:5m" - "180d:30m" # ... rest of your configuration ...
이 구성:
- 거의 쿼리되지 않는 메트릭에 대해 단 1일 만에 10분 해상도 다운샘플링을 적용합니다. - 다른 모든 메트릭에 대해 기존 다운샘플링 정책을 유지합니다.
다운샘플링 규칙의 순서는 중요합니다. 보다 구체적인 규칙은 먼저 나열해야 합니다.

이 대화 중에 보조자는 다음 도구를 사용했습니다.

사용 가능한 테넌트 목록을 얻으려면 tenants .
기능 및 데이터 형식에 대한 정보를 얻기 위한 documentation
사용 가능한 메트릭 목록을 가져오려면 metrics
metrics_staistics 사용하여 메트릭 사용에 대한 정보를 얻습니다.
디버깅을 위한 시계열을 얻기 위한 series
metric_relabel_debug 사용하여 재레이블링 규칙을 디버깅합니다.
인스턴스 매개변수에 대한 정보를 얻기 위한 flags
다운샘플링 구성을 디버깅하기 위한 downsampling_filters_debug

하지만 다른 도구를 사용하고 원하는 대로 결합할 수도 있습니다.

부인 성명

이러한 MCP 서버와 함께 제공되는 AI 서비스 및 에이전트는 결과의 정확성, 완전성 및 신뢰성을 보장할 수 없습니다. AI를 통해 얻은 결과를 다시 한번 확인해야 합니다. MCP 서버와 그 응답의 품질은 클라이언트의 성능과 사용 중인 모델의 품질에 따라 크게 달라집니다.

기여하다

MCP VictoriaMetrics 프로젝트에 대한 기여를 환영합니다! 이슈, 기능 요청 또는 풀 리퀘스트를 자유롭게 제출해 주세요.