grafana/mcp-grafanaView GitHub Homepage for Latest Official Releases

Grafana용 모델 컨텍스트 프로토콜(MCP) 서버로, AI 에이전트가 Grafana 인스턴스 및 해당 생태계에 접근할 수 있도록 지원하며, 대시보드 관리, 데이터 소스 쿼리, 경고 규칙 구성 등의 기능을 제공합니다.

Apache-2.0Gomcp-grafanagrafana 1.3k Last Updated: August 07, 2025

Grafana MCP 서버 프로젝트 상세 소개

프로젝트 개요

Grafana MCP 서버는 모델 컨텍스트 프로토콜 (Model Context Protocol, MCP) 기반 서버로, Grafana 인스턴스 및 주변 생태계와 통합되도록 설계되었습니다. 이 프로젝트는 AI 에이전트(예: Claude Desktop)가 Grafana의 다양한 기능에 액세스하고 조작할 수 있는 기능을 제공합니다.

핵심 기능 특성

대시보드 관리

  • 대시보드 검색: 특정 대시보드를 빠르게 검색하고 찾습니다.
  • 대시보드 가져오기: UID를 통해 전체 대시보드 구성을 가져옵니다.
  • 대시보드 업데이트/생성: 대시보드를 동적으로 수정하거나 새로 생성합니다 (컨텍스트 창 제한에 유의).

데이터 소스 통합

  • 데이터 소스 관리: 데이터 소스 정보를 나열하고 가져옵니다.
  • 다중 데이터 소스 쿼리 지원:
    • Prometheus: PromQL 쿼리를 실행하여 메트릭 데이터를 가져옵니다.
    • Loki: LogQL 쿼리를 실행하여 로그 데이터를 검색합니다.
    • Tempo: 분산 추적 데이터 쿼리
    • Pyroscope: 성능 분석 데이터 쿼리

메타데이터 쿼리

  • Prometheus 메타데이터: 메트릭 메타데이터, 메트릭 이름, 태그 이름 및 태그 값을 가져옵니다.
  • Loki 메타데이터: 로그 태그 이름, 태그 값 및 통계 정보를 가져옵니다.

이벤트 및 경고 관리

  • 이벤트 관리: 이벤트를 검색, 생성, 업데이트 및 종료합니다.
  • 경고 규칙: 경고 규칙 정보를 나열하고 가져오며, 경고 상태를 가져옵니다.
  • 연락처 관리: 경고 연락처를 나열, 생성 및 수정합니다.

Grafana OnCall 통합

  • 근무 일정 관리: 근무 계획을 나열하고 관리합니다.
  • 근무 정보: 근무 상세 정보 및 현재 근무 사용자를 가져옵니다.
  • 팀 및 사용자 관리: 팀 및 사용자 정보를 관리합니다.
  • 경고 그룹 관리: 경고 그룹을 나열합니다.

Sift 조사 기능

  • 스마트 조사: Sift 조사를 시작하고 결과를 확인합니다.
  • 조사 관리: 조사 정보를 생성, 나열 및 가져옵니다.
  • 분석 기능: 조사 분석 결과를 가져옵니다.
  • 오류 패턴 식별: 로그에서 오류 패턴을 찾습니다.
  • 성능 분석: 느린 요청을 식별합니다.

도구 구성

이 프로젝트는 유연한 도구 구성 옵션을 제공하며, 특정 기능 범주를 활성화하거나 비활성화할 수 있습니다.

도구 이름 분류 설명
search_dashboards Search 대시보드 검색
get_dashboard_by_uid Dashboard UID를 통해 대시보드 가져오기
update_dashboard Dashboard 대시보드 업데이트 또는 생성
list_datasources Datasources 데이터 소스 나열
query_prometheus Prometheus Prometheus 쿼리 실행
query_loki_logs Loki 로그 쿼리 및 검색
list_incidents Incident 이벤트 나열
list_alert_rules Alerting 경고 규칙 나열
list_oncall_schedules OnCall OnCall 근무 계획 나열
find_error_pattern_logs Sift 오류 패턴 찾기

--disable-<category> 플래그를 사용하여 특정 도구 범주를 비활성화할 수 있습니다. 예를 들어, --disable-oncall을 사용하면 OnCall 관련 도구를 비활성화할 수 있습니다.

설치 및 구성

설치 방법

1. Docker 이미지
docker pull mcp/grafana
docker run -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_API_KEY=<your_token> mcp/grafana
2. 바이너리 파일 다운로드

릴리스 페이지에서 최신 버전을 다운로드하여 $PATH 디렉토리에 배치합니다.

3. 소스 코드 컴파일
GOBIN="$HOME/go/bin" go install github.com/grafana/mcp-grafana/cmd/mcp-grafana@latest

구성 설정

전제 조건
  1. Grafana에서 서비스 계정을 생성하고 충분한 권한을 할당합니다.
  2. 서비스 계정 토큰을 생성합니다.

Claude Desktop 구성

바이너리 파일 사용:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_API_KEY": "<your service account token>"
      }
    }
  }
}

Docker 사용:

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run", "--rm", "-p", "8000:8000",
        "-e", "GRAFANA_URL", "-e", "GRAFANA_API_KEY",
        "mcp/grafana"
      ],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_API_KEY": "<your service account token>"
      }
    }
  }
}

디버깅 모드

-debug 플래그를 추가하여 디버깅 모드를 활성화하면 자세한 HTTP 요청 및 응답 로그를 제공할 수 있습니다.

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": ["-debug"],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_API_KEY": "<your service account token>"
      }
    }
  }
}

개발 및 테스트

개발 환경 설정

# 서버 실행
make run

# Docker 이미지 빌드
make build-image

# Docker 컨테이너 실행
docker run -it --rm -p 8000:8000 mcp-grafana:latest

테스트 유형

단위 테스트
make test-unit
# 또는
make test
통합 테스트
# Docker 컨테이너 시작 필요
make test-integration
클라우드 테스트
# 클라우드 Grafana 인스턴스 및 자격 증명 필요
make test-cloud
전체 테스트
# 로컬 Grafana 인스턴스 시작
docker-compose up -d

# 모든 테스트 실행
make test-all

코드 품질

코드 검사

make lint

JSON Schema 검사

이 프로젝트에는 jsonschema 구조체 태그에서 이스케이프되지 않은 쉼표를 검사하는 사용자 정의 린터가 포함되어 있습니다.

make lint-jsonschema

기술 아키텍처

  • 프로그래밍 언어: Go
  • 프로토콜: Model Context Protocol (MCP)
  • 통신 방식: stdin/stdout 또는 SSE (Server-Sent Events)
  • 지원되는 클라이언트: Claude Desktop 등 MCP 호환 클라이언트

사용 시나리오

  1. AI 기반 모니터링: AI 에이전트가 모니터링 데이터를 지능적으로 쿼리하고 분석할 수 있도록 합니다.
  2. 자동화된 운영: AI를 통해 대시보드 및 경고 규칙을 자동으로 생성하고 관리합니다.
  3. 지능형 이벤트 대응: AI를 활용하여 로그 및 메트릭을 분석하고 문제를 신속하게 식별하고 해결합니다.
  4. 데이터 통찰력: AI가 복잡한 모니터링 데이터에서 가치 있는 정보를 추출하도록 돕습니다.

이 프로젝트는 AI와 기존 모니터링 도구의 통합이라는 새로운 트렌드를 나타내며, 개발자에게 인공 지능 도우미와 Grafana 생태계를 연결하는 강력한 다리를 제공합니다.

Star History Chart