Claude Code에서 Grafana MCP 연동하기: AI 기반 모니터링 자동화

개요

Grafana는 메트릭, 로그, 트레이스를 시각화하고 모니터링하는 오픈소스 플랫폼입니다. Prometheus, Loki, Tempo 같은 데이터소스와 연동하여 인프라 전반의 상태를 한눈에 파악할 수 있죠. Claude Code의 MCP(Model Context Protocol)를 활용하면 AI 에이전트가 직접 Grafana를 조회하고 분석할 수 있습니다.

이 글에서는 Claude Code에 Grafana MCP를 연동하는 전체 과정과 실제 활용 방법을 정리했습니다.

왜 Grafana MCP인가?

모니터링 대시보드를 직접 열어보는 것도 방법이지만, AI에게 "최근 1시간 동안 에러율이 높은 서비스 찾아줘"라고 말하면 즉시 PromQL을 실행하고 결과를 요약해줍니다. 특히 다음과 같은 상황에서 유용합니다:

• 장애 대응 시: "이 서비스의 최근 로그에서 에러 패턴 분석해줘"
• 성능 분석 시: "지난 24시간 동안 응답 시간 P99가 가장 높았던 시점은?"
• 인시던트 관리: "현재 진행 중인 인시던트 목록 보여줘"
• 대시보드 탐색: "CPU 관련 대시보드 찾아서 요약해줘"

터미널을 벗어나지 않고 자연어로 Grafana를 조작할 수 있다는 것이 핵심입니다.

사전 준비

1. Grafana 인스턴스

로컬 Grafana나 Grafana Cloud 인스턴스가 필요합니다. Grafana Cloud는 무료 플랜도 제공하므로 테스트 용도로 적합합니다.

• Grafana Cloud: https://[인스턴스명].grafana.net 형태의 URL
• 로컬 Grafana: http://localhost:3000

중요: Grafana 9.0 이상 버전이 필요합니다. 일부 API 엔드포인트가 이 버전부터 지원됩니다.

2. 서비스 계정 토큰 발급

Grafana 대시보드에서 서비스 계정을 생성하고 토큰을 발급받습니다:

1. Grafana 대시보드 접속
2. Administration → Service Accounts 메뉴 이동
3. "Add service account" 클릭
4. 이름 입력 (예: "claude-code-mcp")
5. 역할 선택: Editor 권장 (읽기/쓰기 모두 필요시)
6. "Add service account token" 클릭하여 토큰 생성
7. 생성된 토큰 복사 (다시 볼 수 없으므로 안전하게 보관)

토큰은 glsa_로 시작하는 형태입니다.

3. Go 런타임 설치 (바이너리 빌드 방식)

Grafana MCP 서버는 Go로 작성되어 있습니다. 바이너리를 직접 빌드하려면 Go가 필요합니다:

# macOS
brew install go

# 설치 확인
go version

MCP 서버 설치

Grafana MCP 서버를 설치하는 방법은 여러 가지가 있습니다. 저는 Go 바이너리 빌드 방식을 선택했습니다.

방법 1: Go 바이너리 빌드 (권장)

# Go 모듈로 설치
go install github.com/grafana/mcp-grafana/cmd/mcp-grafana@latest

# 설치 확인
which mcp-grafana
# 출력: /Users/[사용자명]/go/bin/mcp-grafana

이 방식의 장점은 npx 실행 시마다 발생하는 패키지 다운로드 오버헤드가 없다는 것입니다. 바이너리가 로컬에 설치되므로 MCP 서버 시작이 빠릅니다.

방법 2: Docker 이미지

# Docker Hub에서 이미지 풀
docker pull mcp/grafana

# STDIO 모드로 실행 (Claude Code 연동용)
docker run --rm -i \
  -e GRAFANA_URL=https://your-instance.grafana.net \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=your-token \
  mcp/grafana -t stdio

방법 3: npx 직접 실행

npx -y mcp-grafana

매번 패키지를 다운로드하므로 초기 실행이 느릴 수 있습니다.

Claude Code 설정

글로벌 설정 (모든 프로젝트에서 사용)

~/.claude.json 파일에 다음을 추가합니다:

{
  "mcpServers": {
    "grafana": {
      "type": "stdio",
      "command": "/Users/[사용자명]/go/bin/mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "https://your-instance.grafana.net",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "glsa_xxxxxxxxxxxx"
      }
    }
  }
}

설정 항목 설명

항목	설명
type	MCP 통신 방식. stdio는 표준 입출력 사용
command	MCP 서버 실행 경로 (Go 바이너리 전체 경로)
GRAFANA_URL	Grafana 인스턴스 URL
GRAFANA_SERVICE_ACCOUNT_TOKEN	발급받은 서비스 계정 토큰

설정 확인

Claude Code를 재시작한 후 /mcp 명령어로 연결 상태를 확인합니다:

$ claude

> /mcp

Checking MCP server health...

grafana: /Users/jeongkichang/go/bin/mcp-grafana - ✓ Connected

연결이 성공하면 다음과 같은 도구들이 사용 가능해집니다:

mcp__grafana__search_dashboards
mcp__grafana__list_datasources
mcp__grafana__query_prometheus
mcp__grafana__query_loki_logs
mcp__grafana__list_incidents
...

주요 기능

Grafana MCP는 다양한 기능을 제공합니다. 주요 카테고리별로 정리하면:

대시보드 관리

• search_dashboards: 대시보드 검색
• get_dashboard_by_uid: 특정 대시보드 상세 조회
• get_dashboard_summary: 대시보드 요약 정보 (컨텍스트 절약)
• update_dashboard: 대시보드 생성/수정

Prometheus 쿼리

• query_prometheus: PromQL 쿼리 실행
• list_prometheus_metric_names: 메트릭 이름 목록
• list_prometheus_label_values: 레이블 값 조회

Loki 로그

• query_loki_logs: LogQL로 로그 조회
• list_loki_label_names: 레이블 이름 목록
• query_loki_stats: 로그 스트림 통계

알림 및 인시던트

• list_alert_rules: 알림 규칙 목록
• list_incidents: 인시던트 목록
• create_incident: 인시던트 생성

OnCall

• list_oncall_schedules: 온콜 스케줄 조회
• get_current_oncall_users: 현재 온콜 담당자

실제 활용 예시

예시 1: 데이터소스 확인

사용자: 연결된 데이터소스 목록 보여줘

Claude: [mcp__grafana__list_datasources 호출]

현재 Grafana에 연결된 데이터소스입니다:

| 이름 | 타입 | UID |
|------|------|-----|
| grafanacloud-prom | prometheus | xxxxx |
| grafanacloud-logs | loki | xxxxx |
| grafanacloud-traces | tempo | xxxxx |

예시 2: Prometheus 쿼리

사용자: 최근 5분간 평균 CPU 사용률 쿼리해줘

Claude: [mcp__grafana__query_prometheus 호출]
- datasourceUid: grafanacloud-prom
- query: avg(rate(node_cpu_seconds_total{mode!="idle"}[5m])) * 100

결과: 현재 평균 CPU 사용률은 23.5%입니다.

예시 3: 대시보드 검색

사용자: 쿠버네티스 관련 대시보드 찾아줘

Claude: [mcp__grafana__search_dashboards 호출]
- query: kubernetes

3개의 대시보드를 찾았습니다:

1. Kubernetes / Compute Resources / Cluster
   - UID: k8s-cluster
   - 폴더: Kubernetes

2. Kubernetes / Networking / Pod
   - UID: k8s-pod-networking
   - 폴더: Kubernetes

...

장점 정리

1. 자연어 인터페이스

PromQL이나 LogQL 문법을 외우지 않아도 됩니다. "에러 로그 보여줘"라고 말하면 Claude가 적절한 쿼리를 생성합니다. 물론 복잡한 쿼리는 직접 작성하는 것이 정확하지만, 빠른 탐색에는 충분합니다.

2. 컨텍스트 유지

터미널에서 코드를 수정하다가 "방금 배포한 서비스 메트릭 확인해줘"라고 바로 요청할 수 있습니다. 별도 도구로 전환하지 않아도 됩니다.

3. 분석 자동화

단순 조회를 넘어 "지난 주 대비 에러율 변화 분석해줘" 같은 요청도 가능합니다. Claude가 여러 쿼리를 조합하여 인사이트를 제공합니다.

4. 문서화 지원

대시보드 구조나 알림 규칙을 분석하고 문서로 정리하는 것도 가능합니다. "이 대시보드의 패널들이 어떤 메트릭을 보여주는지 설명해줘"라고 하면 됩니다.

5. 인시던트 대응 가속

장애 상황에서 여러 대시보드를 오가며 원인을 찾는 대신, "최근 30분간 에러가 급증한 서비스와 관련 로그 분석해줘"라고 요청하면 Claude가 종합적으로 분석합니다.

주의사항

보안

서비스 계정 토큰은 민감한 정보입니다. 설정 파일에 직접 입력하는 대신 환경 변수나 시크릿 매니저 활용을 고려하세요.

권한 최소화

MCP 서버가 모든 기능에 접근할 필요는 없습니다. --disable-write 플래그로 읽기 전용 모드를 활성화하거나, 서비스 계정 권한을 Viewer로 제한할 수 있습니다:

{
  "mcpServers": {
    "grafana": {
      "command": "/Users/[사용자명]/go/bin/mcp-grafana",
      "args": ["--disable-write"],
      "env": { ... }
    }
  }
}

컨텍스트 윈도우

대시보드 전체 JSON을 가져오면 컨텍스트를 많이 소비합니다. get_dashboard_summary나 get_dashboard_property를 활용하여 필요한 정보만 조회하는 것이 좋습니다.

마치며

Grafana MCP를 연동하고 나니 모니터링 작업 흐름이 한결 편해졌습니다. 특히 개발 중에 빠르게 메트릭을 확인하거나, 배포 후 상태를 점검할 때 유용합니다. 대시보드를 직접 열어보는 것과 AI에게 요약을 요청하는 것은 각각의 쓰임새가 있지만, 선택지가 늘어났다는 것 자체가 의미 있다고 생각합니다.

공식 저장소(github.com/grafana/mcp-grafana)에서 더 자세한 설정 옵션과 기능을 확인할 수 있습니다.