grafana-mcp

Grafana API의 일부를 MCP(Model Context Protocol) 서버로 노출하여 자연어 로그 쿼리에 집중합니다. 주요 목표는 LogQL, 레이블, 데이터 소스 UID를 직접 다룰 필요 없이 "지난 30분 동안 api 서비스에서 발생한 에러 로그를 보여줘"라고 말하고 실제 로그 라인을 받아보는 것입니다.

로그 데이터 소스, Loki 레이블, 서비스 이름과 호스팅 데이터 소스/레이블 간의 매핑은 디스크에 캐시되므로 반복 호출 시 불필요한 레이블 스캔을 건너뜁니다.

한국어 문서 / Korean README

설치 및 설정

npx (설치 불필요)

~/.mcp.json에 다음을 추가하세요.

{
  "mcpServers": {
    "grafana": {
      "command": "npx",
      "args": ["@seungje.jun/grafana-mcp"],
      "env": {
        "GRAFANA_URL": "https://grafana.example.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "glsa_xxx"
      }
    }
  }
}

소스에서 빌드

git clone https://github.com/ninanung/grafana-mcp.git
cd grafana-mcp
npm install
npm run build

{
  "mcpServers": {
    "grafana": {
      "command": "node",
      "args": ["/path/to/grafana-mcp/dist/cli.js"],
      "env": {
        "GRAFANA_URL": "https://grafana.example.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "glsa_xxx"
      }
    }
  }
}

Claude Code를 재시작하여 MCP 도구를 활성화하세요.

인증

다음 중 하나가 필요합니다. 아래 순서대로 확인하며, 가장 먼저 발견된 것이 적용됩니다.

모든 Bearer 스타일 토큰은 Authorization: Bearer <token>으로 전송됩니다. 서버는 토큰의 종류를 구분하지 않으며, 설정된 토큰을 사용합니다.

환경 변수

Related MCP server: Log Analyzer MCP Server

도구

사용 예시

MCP 클라이언트에 의해 조정되는 일반적인 자연어 흐름:

1. 사용자: "지난 30분 동안 api 서비스에서 발생한 에러 로그를 보여줘."

2. service: "api", level: "error", time_from: "now-30m"과 함께 query_logs 호출 → 서버가 service="api" 레이블을 소유한 Loki 데이터 소스를 자동 감지하고 LogQL을 실행합니다.

3. (첫 호출 시) 서비스 → 데이터 소스/레이블 매핑이 캐시에 저장되며, 이후 호출은 감지 단계를 건너뜁니다.

4. 사용자: "그 에러들을 패턴별로 요약해줘." → output: "summarize"와 함께 동일한 호출을 수행하면 패턴별로 그룹화된 카운트가 반환됩니다.

5. 사용자: "다른 서비스는 뭐가 있지?" → list_services가 전체 서비스 목록을 반환합니다.

서비스 이름에 오타가 있는 경우, query_logs는 유사한 일치 항목을 제안합니다 (예: Did you mean: checkout, checkout-api?).

자동 감지 작동 방식

query_logs는 대상 데이터 소스와 레이블을 스스로 선택합니다:

1. 모든 데이터 소스를 로그 유형(Loki/ES/CloudWatch/OpenSearch/Splunk)으로 필터링합니다.

2. 각 Loki 데이터 소스에 대해 /loki/api/v1/labels를 가져와 일반적인 서비스 레이블 후보(service, service_name, app, app_name, application, container, job)를 먼저 확인한 다음 나머지 레이블을 확인합니다.

3. 각 후보 레이블에 대해 값을 가져와 요청된 service 이름이 해당 목록에 있는지 확인합니다.

4. 정확히 하나의 (datasource, label) 쌍이 일치하면 이를 사용합니다. 여러 개가 일치하면 datasource_uid를 요구하여 명확히 합니다. 일치하는 항목이 없으면 유사한 이름 제안을 반환합니다.

5. 해석된 (service → ds_uid, label)은 캐시됩니다. refresh: true 또는 refresh_log_cache를 사용하면 재감지를 강제할 수 있습니다.

자동 감지는 현재 Loki만 지원합니다. Elasticsearch / CloudWatch / Splunk 데이터 소스의 경우 datasource_uid와 service_label을 명시적으로 전달하세요 (LogQL 전용 필터는 적용되지 않을 수 있습니다).

출력 모드

query_logs는 output 인수를 허용합니다:

• raw (기본값): <ISO timestamp> <log line> — 터미널에서 직접 읽기에 적합합니다.

• summarize: 라인을 정규화된 패턴(숫자 → N, UUID → UUID)별로 그룹화하여 카운트와 패턴별 샘플을 제공합니다. 로그가 너무 많거나 노이즈가 심할 때 사용하세요.

• json: 구조화된 객체 { ts, line, labels } — 다운스트림 도구용입니다.

캐시

• 로그 캐시: ~/.grafana-mcp/log-cache.json에 저장됩니다. Grafana 기본 URL별로 키가 지정되어 여러 인스턴스가 충돌하지 않습니다.

• 각 카테고리별로 고유한 TTL(데이터 소스 / 레이블 / 레이블 값 / 서비스 해석)이 있습니다. 위의 환경 변수 표를 참조하세요.

• 나중에 실패하는 캐시된 서비스 해석(예: 레이블 이름 변경)은 자동으로 무효화되어 다음 호출 시 재감지됩니다.

• get_log_cache로 검사하고, refresh_log_cache로 삭제하며, export_log_cache / import_log_cache로 팀원과 공유할 수 있습니다.

캐시 위치 및 초기화

캐시 파일은 일반 JSON 문서이므로 직접 검사, 편집 또는 백업할 수 있습니다.

안전 및 제약 사항

• 읽기 전용: 서버는 Grafana 상태를 변경하는 어떠한 엔드포인트도 노출하지 않습니다. 대시보드/데이터 소스 CRUD나 알림 변경은 없습니다.

• Stdio 로그: 모든 로그는 stderr로 출력되어 MCP stdio 채널을 깨끗하게 유지합니다.

• TLS 건너뛰기: GRAFANA_TLS_SKIP_VERIFY=true는 프로세스 전체에서 NODE_TLS_REJECT_UNAUTHORIZED=0을 설정합니다. 신뢰할 수 있는 네트워크 내의 자체 서명된 Grafana에만 사용하세요.

• 비밀 정보 로깅 금지: 인증 토큰은 감사 로그에 기록되지 않습니다.

라이선스

MIT