Grafana

공식

Grafana 인스턴스에서 대시보드를 검색하고, 인시던트를 조사하며, 데이터 소스를 쿼리합니다.

GitHub
3.7k

Grafana MCP(으)로 무엇을 할 수 있나요?

  • 대시보드 검색 및 살펴보기 — 제목, 폴더, 태그 또는 즐겨찾기 여부로 대시보드를 찾고, 전체 JSON 대신 간결한 요약이나 특정 속성을 가져옵니다.
  • Prometheus 및 Loki 쿼리 — PromQL 메트릭 쿼리와 LogQL 로그 또는 메트릭 쿼리를 실행하고, 메트릭 메타데이터, 레이블 값, 감지된 로그 패턴을 가져옵니다.
  • SQL 및 기타 데이터 소스 쿼리 실행 — ClickHouse, Snowflake, Athena, MySQL, PostgreSQL, MSSQL, BigQuery에서 SQL을 실행하거나 InfluxDB, CloudWatch, Graphite, Elasticsearch를 쿼리합니다.
  • 알림 관리 — 알림 규칙과 발화 상태를 확인하고, 규칙을 생성하거나 업데이트하며, 알림 정책, 연락 지점, 시간 간격을 검토합니다.
  • 인시던트 및 온콜 처리 — Grafana Incident 레코드를 검색하고 생성하며, OnCall 일정, 교대 근무, 현재 온콜 사용자, 알림 그룹을 확인합니다.
  • 패널 및 대시보드 렌더링 — 보고서에 사용할 대시보드 또는 패널의 PNG 이미지를 사용자 지정 크기, 시간 범위, 테마, 변수로 생성합니다.

문서

Grafana MCP 서버

Unit Tests Integration Tests E2E Tests Go Reference MCP Catalog

Grafana용 Model Context Protocol (MCP) 서버입니다.

Grafana 인스턴스와 주변 생태계에 액세스할 수 있습니다.

빠른 시작

uv가 필요합니다. MCP 클라이언트 구성(예: Claude Desktop, Cursor)에 다음을 추가하세요.

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

Grafana Cloud의 경우 GRAFANA_URL를 인스턴스 URL(예: https://myinstance.grafana.net)로 바꾸세요. Docker, 바이너리, Helm을 포함한 추가 설치 옵션은 사용법을 참조하세요.

요구 사항

  • 전체 기능을 사용하려면 Grafana 버전 9.0 이상이 필요합니다. API 엔드포인트가 없어 이전 버전에서는 일부 기능, 특히 데이터 소스 관련 작업이 제대로 작동하지 않을 수 있습니다.

기능

현재 MCP 서버에서 사용할 수 있는 기능은 다음과 같습니다. 이 목록은 정보 제공용이며 향후 기능에 대한 로드맵이나 약속을 의미하지 않습니다.

대시보드

  • 대시보드 검색: 제목, 폴더 UID, 태그 또는 즐겨찾기 상태로 대시보드를 찾습니다.
  • UID로 대시보드 가져오기: 고유 식별자를 사용해 대시보드의 전체 세부 정보를 가져옵니다. 현재 대시보드 대신 저장된 스냅샷을 불러오려면 선택적 version를 전달하세요. 경고: 대시보드가 크면 컨텍스트 창 공간을 많이 사용할 수 있습니다.
  • 대시보드 버전 목록: 대시보드의 저장된 버전을 간결한 메타데이터(버전 번호, 작성자, 타임스탬프, 저장 메시지)로 나열합니다.
  • 대시보드 요약 가져오기: 전체 JSON 없이 제목, 패널 수, 패널 유형, 변수, 메타데이터를 포함한 간결한 대시보드 개요를 가져와 컨텍스트 창 사용량을 최소화합니다.
  • 대시보드 속성 가져오기: JSONPath 표현식(예: $.title, $.panels[*].title)을 사용해 대시보드의 특정 부분만 추출하여 필요한 데이터만 가져오고 컨텍스트 창 사용량을 줄입니다.
  • 대시보드 업데이트 또는 생성: 기존 대시보드를 수정하거나 새 대시보드를 만듭니다. 경고: 전체 대시보드 JSON이 필요하며 컨텍스트 창 공간을 많이 사용할 수 있습니다.
  • 대시보드 패치: 전체 JSON 없이 대시보드에 특정 변경 사항을 적용하여 대상 수정에 필요한 컨텍스트 창 사용량을 크게 줄입니다.
  • 패널 쿼리 및 데이터 소스 정보 가져오기: 대시보드의 모든 패널에서 제목, 쿼리 문자열, 데이터 소스 정보(사용 가능한 경우 UID 및 유형 포함)를 가져옵니다.

패널 쿼리 실행

참고: 패널 쿼리 실행 도구는 기본적으로 비활성화되어 있습니다. 활성화하려면 runpanelquery을 --enabled-tools 플래그에 추가하세요.

  • 패널 쿼리 실행: 사용자 지정 시간 범위와 변수 재정의를 사용해 대시보드 패널의 쿼리를 실행합니다. Infinity 패널은 쿼리에서 backend 또는 jq-backend 파서를 사용할 때 실행됩니다(Google Sheets 쿼리는 항상 해당 파서를 사용함). 기본 simple 파서와 UQL 및 GROQ 파서는 브라우저에서만 작동합니다. kniepdennis-neo4j-datasource 플러그인의 Neo4j 패널은 플러그인을 통해 Cypher 쿼리를 실행하며, 읽기 전용 세션을 엽니다. Elasticsearch 패널은 Grafana와 동일하게 lucene 형식으로 Lucene 쿼리의 변수를 보간하며, 자동 날짜 히스토그램은 $__interval와 동일한 간격을 사용합니다.

컨텍스트 창 관리

대시보드 도구에는 컨텍스트 창 사용량을 효과적으로 관리하기 위한 몇 가지 전략이 포함되어 있습니다(이슈 #101).

  • 대시보드 개요를 확인하고 수정 계획을 세울 때는 get_dashboard_summary를 사용하세요.
  • 대시보드의 특정 부분만 필요한 경우 JSONPath와 함께 get_dashboard_property을 사용하세요.
  • 전체 대시보드 JSON이 꼭 필요한 경우가 아니라면 get_dashboard_by_uid을 사용하지 마세요.

데이터 소스

  • 데이터 소스 정보 나열 및 가져오기: 구성된 모든 데이터 소스를 확인하고 각 데이터 소스의 세부 정보를 가져옵니다.
    • 지원되는 데이터 소스 유형: Prometheus, Loki, ClickHouse, CloudWatch, Elasticsearch, OpenSearch, Snowflake, Athena.
  • 데이터 소스 리소스: 액세스할 수 있는 각 데이터 소스는 grafana://datasources/{uid}의 MCP 리소스로도 노출되므로, 모델이 직접 조회하는 대신 대화에 바로 첨부할 수 있습니다(예: Claude Code에서 @ 사용). 데이터 소스 도구와 함께 비활성화됩니다.

쿼리 예시

참고: 쿼리 예시 도구는 기본적으로 비활성화되어 있습니다. 활성화하려면 examples을 --enabled-tools 플래그에 추가하세요.

  • 쿼리 예시 가져오기: 쿼리 구문을 익힐 수 있도록 다양한 데이터 소스 유형의 쿼리 예시를 가져옵니다.

Prometheus 쿼리

  • Prometheus 쿼리: Prometheus 데이터 소스에서 PromQL 쿼리를 실행합니다(즉시 메트릭 쿼리와 범위 메트릭 쿼리 모두 지원).
  • Prometheus 메타데이터 쿼리: Prometheus 데이터 소스에서 메트릭 메타데이터, 메트릭 이름, 레이블 이름, 레이블 값을 가져옵니다.
  • 히스토그램 백분위수 쿼리: histogram_quantile을 사용해 히스토그램 백분위수 값(p50, p90, p95, p99)을 계산합니다.

Loki 쿼리

  • Loki 로그 및 메트릭 쿼리: Loki에서 LogQL을 사용해 로그 쿼리와 메트릭 쿼리를 모두 실행합니다.
  • Loki 메타데이터 쿼리: Loki에서 레이블 이름, 레이블 값, 스트림 통계를 가져옵니다.
  • Loki 패턴 쿼리: Loki가 감지한 로그 패턴을 가져와 일반적인 로그 구조와 이상 징후를 식별합니다.

InfluxDB 쿼리

참고: InfluxDB 도구는 기본적으로 비활성화되어 있습니다. 활성화하려면 influxdb를 --enabled-tools 플래그에 추가하세요.

  • InfluxDB 쿼리: InfluxDB 데이터 소스에서 InfluxQL(v1.x) 또는 Flux(v2.x)를 사용해 쿼리를 실행합니다. 방언은 데이터 소스 구성에서 추론하거나 dialect 매개변수로 명시적으로 설정할 수 있습니다.

SQL 데이터 소스 쿼리

참고: SQL 도구는 기본적으로 비활성화되어 있습니다. 활성화하려면 sql를 --enabled-tools 플래그에 추가하세요. 이전 버전과의 호환성을 위한 별칭 clickhouse, snowflake, athena도 사용할 수 있습니다.

통합 SQL 도구는 단일 도구 집합을 통해 ClickHouse, Snowflake, Athena, MySQL, PostgreSQL, MSSQL, BigQuery를 지원합니다. 쿼리는 Grafana의 데이터 소스 플러그인을 거치므로 인증은 데이터 소스 구성에서 처리되며, 자격 증명은 MCP 서버에 전달되지 않습니다.

  • 데이터베이스/스키마/카탈로그 나열: SQL 데이터 소스의 조직 단위를 검색합니다. Athena의 경우 카탈로그를 생략하면 카탈로그를 나열하고, 카탈로그를 전달하면 데이터베이스를 나열합니다.
  • 테이블 나열: 데이터베이스 또는 스키마의 테이블을 메타데이터(사용 가능한 경우 행 수와 크기 포함)와 함께 나열합니다.
  • 테이블 스키마 설명: 열 이름, 유형, null 허용 여부, 기본값, 설명을 가져옵니다.
  • SQL 쿼리: 데이터 소스별 매크로 대체($__timeFilter(col), $__from/$__to, $__interval, ${varname}), 자동 제한 적용, 템플릿 변수 지원을 통해 SQL 쿼리를 실행합니다.

BigQuery의 경우 Grafana에서 grafana-bigquery-datasource 플러그인을 구성하세요. 검색에는 프로젝트에 database, 데이터 세트에 schema을 사용합니다. database을 생략하면 프로젝트는 먼저 데이터 소스의 defaultProject을 사용하고, 그다음 플러그인의 /defaultProjects 엔드포인트를 사용합니다(GCE 프로젝트 검색 포함). 메타데이터는 쿼리 작업이나 테이블 스캔 없이 API만을 통해 가져옵니다. 열 설명과 중첩 유형이 포함되며, 플러그인은 테이블 설명/유형, 열의 null 허용 여부, 기본값을 제공하지 않습니다.

BigQuery 쿼리에는 `my-project.my_dataset.fct_events` and use the datasource's billing project. Optional location defaults to datasource processingLocation. Use ${name:sqlstring}와 같은 정규화된 테이블 참조가 필요합니다. 행 제한은 스캔 바이트나 쿼리 비용을 제한하지 않습니다.

CloudWatch 쿼리

참고: CloudWatch 도구는 기본적으로 비활성화되어 있습니다. 활성화하려면 cloudwatch를 --enabled-tools 플래그에 추가하세요.

  • CloudWatch 네임스페이스 나열: 사용 가능한 AWS CloudWatch 네임스페이스를 검색합니다.
  • CloudWatch 메트릭 나열: 특정 네임스페이스에서 사용 가능한 메트릭을 나열합니다.
  • CloudWatch 차원 나열: 메트릭 쿼리 필터링에 사용할 차원을 가져옵니다.
  • CloudWatch 쿼리: 시간 범위를 지정해 CloudWatch 메트릭 쿼리를 실행합니다.
  • CloudWatch 로그 그룹 나열: 선택적으로 이름 접두사로 필터링하여 로그 그룹을 검색합니다.
  • CloudWatch 로그 그룹 필드 나열: 로그 그룹에서 사용 가능한 필드를 검색합니다.
  • CloudWatch Logs 쿼리: 하나 이상의 로그 그룹에서 CloudWatch Logs Insights 쿼리를 실행합니다.

Google Cloud Logging 쿼리

참고: Google Cloud Logging 도구는 기본적으로 비활성화되어 있습니다. 활성화하려면 cloudlogging을 --enabled-tools 플래그에 추가하세요. Grafana 11.2 이상이 필요한 Google Cloud Logging 데이터 소스 플러그인 (googlecloud-logging-datasource) 버전 1.8.0 이상이 필요합니다. 이전 플러그인 버전은 응답 레이아웃이 다르며, query_cloud_logging은 업그레이드를 요청하는 오류를 반환합니다.

  • Cloud Logging 프로젝트 나열: 데이터 소스가 로그를 읽을 수 있는 GCP 프로젝트 ID를 검색합니다.
  • Cloud Logging 버킷 및 뷰 나열: 쿼리 범위를 지정할 로그 버킷과 로그 뷰를 검색합니다.
  • Cloud Logging 쿼리: 시간 범위와 제한을 지정해 Cloud Logging 쿼리 언어 필터(예: resource.type="k8s_container" AND severity>=ERROR)를 실행합니다. 심각도, 본문, 레이블, 추적 ID가 포함된 항목을 최신순으로 반환합니다. GCP 인증은 데이터 소스 구성에서 처리됩니다.

Graphite 쿼리

참고: Graphite 도구는 기본적으로 비활성화되어 있습니다. 활성화하려면 graphite를 --enabled-tools 플래그에 추가하세요.

  • Graphite 쿼리: Graphite 데이터 소스에서 Graphite 렌더 API 쿼리를 실행합니다.
  • Graphite 메트릭 나열: Graphite 메트릭 경로를 탐색하고 검색합니다.
  • Graphite 태그 나열: 사용 가능한 Graphite 태그와 태그 값을 나열합니다.
  • Graphite 밀도 쿼리: 지정된 패턴에 대해 Graphite 메트릭 밀도를 쿼리합니다.

Elasticsearch/OpenSearch 쿼리

참고: Elasticsearch/OpenSearch 도구는 기본적으로 비활성화되어 있습니다. 활성화하려면 elasticsearch를 --enabled-tools 플래그에 추가하세요.

  • Elasticsearch/OpenSearch 쿼리: Lucene 쿼리 구문 또는 Elasticsearch Query DSL을 사용해 Elasticsearch 또는 OpenSearch 데이터 소스에서 검색 쿼리를 실행합니다. 시간 범위별 필터링과 로그, 메트릭 또는 색인된 데이터 검색을 지원합니다. 색인, ID, 소스 필드, 선택적 관련성 점수가 포함된 문서를 반환합니다.

Quickwit 쿼리

참고: Quickwit 도구는 기본적으로 비활성화되어 있습니다. 활성화하려면 quickwit을 --enabled-tools 플래그에 추가하세요.

  • Quickwit 쿼리: Lucene 쿼리 구문 또는 Elasticsearch와 부분적으로 호환되는 Query DSL을 사용해 Quickwit 데이터 소스에서 검색 쿼리를 실행합니다. 시간 범위별 필터링과 로그 또는 기타 색인된 문서 검색을 지원합니다. 색인, ID, 소스 필드, 선택적 관련성 점수가 포함된 문서를 반환합니다.

에이전트 관측성

참고: 에이전트 관측성 도구는 기본적으로 비활성화되어 있으며 Grafana Cloud에서만 작동합니다. 활성화하려면 agento11y을 --enabled-tools 플래그에 추가하세요.

  • 대화 목록 및 검색: 최근 LLM 대화를 나열하거나 시간 범위 내에서 필터 표현식(모델, 제공자, 에이전트, 상태, 오류 유형, 평가 결과 등)을 사용해 검색합니다. 검색 결과에는 오류 수, 평점 요약, 평가 요약, 추적 ID가 포함됩니다.
  • 대화 세부 정보 가져오기: 프롬프트와 출력을 포함해 모든 생성 결과가 담긴 단일 대화를 가져옵니다.
  • 생성 세부 정보 및 점수 가져오기: ID로 단일 생성 결과와 평가 점수(평가자, 점수 키, 값, 통과 여부, 설명)를 가져옵니다.
  • 에이전트 카탈로그 읽기: 텔레메트리를 전송하는 에이전트를 나열하고, 에이전트 버전 하나의 전체 정보(완전한 시스템 프롬프트, JSON 스키마가 포함된 모든 도구, 실행된 모델)를 가져오며, 에이전트의 버전 기록을 살펴보고 버전별 평가 점수 집계를 비교합니다. 유효 버전은 sha256: 해시이므로 도구 변경의 영향을 받지 않습니다. 자체 버전을 보고하지 않는 에이전트의 경우 시스템 프롬프트를 해시하므로 프롬프트를 수정하면 새 버전이 생성됩니다. 카탈로그 및 버전 행에는 token_estimate이 포함되므로 전체 프롬프트를 가져오기 전에 확인하는 것이 좋습니다.
  • 평가자 및 템플릿 검사: 점수가 나온 평가자, 평가자가 파생된 템플릿, LLM 평가자 평가에 사용할 수 있는 심판 제공자 및 모델을 확인합니다. 쓰기 도구를 활성화하면 평가자를 생성, 분기, 테스트, 삭제할 수도 있습니다.
  • 평가 규칙 및 가드 검사: 평가자를 프로덕션 트래픽에 연결하는 비동기 평가 규칙과 인라인으로 실행되어 경고하거나 거부할 수 있는 가드(후크 규칙)를 확인합니다. 쓰기 도구를 활성화하면 이를 생성, 업데이트, 미리 보기, 삭제할 수도 있습니다. 쓰기 작업과 영구 저장되지 않는 preview_rule 및 test_evaluator 작업에는 grafana-agento11y-app.eval:write 권한이 필요하며, 이 권한은 Agento11y Admin 역할에서 부여됩니다.
  • 저장된 대화 및 컬렉션 관리: 대화에 안정적인 ID, 이름, 태그를 부여하는 북마크인 저장된 대화와 이를 그룹화하는 컬렉션을 확인합니다. 각 컬렉션의 구성원 수와 저장된 대화 행마다 포함된 컬렉션도 확인할 수 있습니다. 쓰기 도구를 활성화하면 대화를 북마크하고, 컬렉션을 생성 및 편집하고, 구성원을 추가하거나 제거할 수도 있습니다. 이러한 쓰기 작업에는 동일한 grafana-agento11y-app.eval:write 권한이 필요합니다.
  • 테스트 스위트 읽기 및 편집: 오프라인 실험에서 사용하는 버전 관리 테스트 스위트를 나열하고, 전체 버전 기록이 포함된 스위트 하나를 읽으며, 특정 버전의 테스트 케이스를 페이지 단위로 확인합니다. 쓰기 도구를 활성화하면 스위트를 생성하고, 이름이나 태그를 변경하고, 초안 버전을 열고, 게시하고, 테스트 케이스를 작성하거나 삭제할 수도 있습니다. 게시된 버전은 고정되므로 편집하려면 새 초안을 열어야 합니다. 이러한 쓰기 작업에는 grafana-agento11y-app.eval:write이 필요합니다.
  • 오프라인 실험 읽기: 테스트 스위트에 대한 평가 실행을 나열하고, 주요 통과율, 비용, 토큰 합계가 포함된 실행 하나를 읽습니다. 테스트 케이스별 보고서에서 각 심판의 설명이 포함된 점수와 아티팩트 메타데이터가 있는 시도까지 자세히 살펴볼 수 있습니다. 쓰기 도구를 활성화하면 실험의 이름이나 태그를 변경하고 실행 중인 실험을 취소할 수도 있으며, 이 작업에는 grafana-agento11y-app.eval:write이 필요합니다. 실험은 SDK 러너가 생성하며 이 도구로 생성하지 않습니다.

Grafana Assistant

참고: Assistant 도구는 기본적으로 비활성화되어 있으며 대상 Grafana 인스턴스에 Grafana Assistant 플러그인(grafana-assistant-app)을 설치해야 합니다. 또한 쓰기 도구이므로(Assistant가 스택 상태를 변경할 수 있음) --disable-write가 설정되어 있으면 건너뜁니다. 활성화하려면 assistant을 --enabled-tools 플래그에 추가하세요.

  • Assistant에 질문하기: Grafana Assistant에 자연어 프롬프트를 보내고 전체 텍스트 응답을 기다립니다. Assistant는 도구, 메트릭, 로그 및 기타 스택 컨텍스트를 사용할 수 있으므로, 격리된 데이터 소스 쿼리 하나를 실행하는 것보다 더 폭넓은 작업을 수행할 수 있습니다. 후속 호출에서 반환된 contextId을 전달하면 같은 대화를 이어갈 수 있습니다. 복잡한 작업은 몇 분이 걸릴 수 있으며, 응답이 완료되거나 요청 시간이 초과될 때까지(5분) 호출이 대기합니다.

인시던트

  • 인시던트 검색, 생성 및 업데이트: 검색, 생성, 활동 추가, 사용자 지정 필드 읽기 또는 설정을 포함해 Grafana Incident에서 인시던트를 관리합니다.
  • 인시던트 리소스: 지난 30일 이내에 시작된 활성 인시던트는 grafana://irm/incidents/{id}의 MCP 리소스로도 제공되므로 대화에 직접 연결할 수 있습니다(예: Claude Code에서 @ 사용). 인시던트 도구와 함께 비활성화됩니다.

알림

  • 알림 규칙 정보 나열 및 가져오기: Grafana에서 알림 규칙과 상태(발생 중/정상/오류 등)를 확인합니다. Grafana 관리 규칙과 Prometheus 또는 Loki 데이터 소스의 데이터 소스 관리 규칙을 모두 지원합니다.
  • 알림 규칙 생성 및 업데이트: 새 알림 규칙을 생성하거나 기존 규칙을 수정합니다.
  • 알림 규칙 삭제: UID로 알림 규칙을 제거합니다.
  • 알림 라우팅 관리: 알림 정책, 연락 지점, 시간 간격을 확인합니다. Grafana 관리 연락 지점과 외부 Alertmanager 데이터 소스(Prometheus Alertmanager, Mimir, Cortex)의 수신기를 모두 지원합니다.

Grafana OnCall

  • 일정 나열 및 관리: Grafana OnCall의 온콜 일정을 확인하고 관리합니다.
  • 교대 세부 정보 가져오기: 특정 온콜 교대에 대한 자세한 정보를 가져옵니다.
  • 현재 온콜 사용자 가져오기: 일정에서 현재 온콜 중인 사용자를 확인합니다.
  • 팀 및 사용자 나열: 모든 OnCall 팀과 사용자를 확인합니다.
  • 알림 그룹 나열: 상태, 통합, 레이블, 시간 범위 등 다양한 기준으로 Grafana OnCall의 알림 그룹을 확인하고 필터링합니다.
  • 알림 그룹 세부 정보 가져오기: ID로 특정 알림 그룹의 자세한 정보를 가져옵니다.

관리자

참고: 관리자 도구는 기본적으로 비활성화되어 있습니다. 활성화하려면 admin를 --enabled-tools 플래그에 포함하세요.

  • 팀 나열: Grafana에 구성된 모든 팀을 확인합니다.
  • 사용자 나열: Grafana 조직의 모든 사용자를 확인합니다.
  • 모든 역할 나열: 선택적으로 위임 가능한 역할을 필터링하여 모든 Grafana 역할을 나열합니다.
  • 역할 세부 정보 가져오기: UID로 특정 Grafana 역할의 세부 정보를 가져옵니다.
  • 역할 할당 나열: 역할에 할당된 모든 사용자, 팀, 서비스 계정을 나열합니다.
  • 사용자 역할 나열: 한 명 이상의 사용자에게 할당된 모든 역할을 나열합니다.
  • 팀 역할 나열: 한 개 이상의 팀에 할당된 모든 역할을 나열합니다.
  • 리소스 권한 나열: 특정 리소스(대시보드, 데이터 소스, 폴더 등)에 정의된 모든 권한을 나열합니다.
  • Grafana 리소스 설명: 리소스 유형에 사용할 수 있는 권한과 할당 기능을 나열합니다.

사용자

  • 사용자 정보: 현재 Grafana ID(로그인, 이메일, 이름, Grafana(서버) 관리자 여부, 현재 조직, 자격 증명으로 액세스할 수 있는 조직 및 각 조직의 역할)를 가져옵니다. 다중 조직 요청에 사용할 수 있는 유효한 orgId 값을 확인할 때 사용합니다.

탐색

  • 딥링크 생성: LLM이 URL을 추측하도록 하지 않고 Grafana 리소스에 대한 정확한 딥링크 URL을 생성합니다.
    • 대시보드 링크: UID를 사용해 대시보드로 바로 연결되는 링크를 생성합니다(예: http://localhost:3000/d/dashboard-uid).
    • 패널 링크: viewPanel 매개변수를 사용해 대시보드 내 특정 패널로 연결되는 링크를 생성합니다(예: http://localhost:3000/d/dashboard-uid?viewPanel=5).
    • Explore 링크: 사전 구성된 데이터 소스를 사용해 Grafana Explore 링크를 생성합니다(예: http://localhost:3000/explore?schemaVersion=1&panes={"a":{"datasource":"prometheus-uid"}}). Grafana 10.2 미만 버전은 panes을 인식하지 못하므로 해당 버전에서는 대신 기존 ?left={...} 형식을 출력합니다.
    • 시간 범위 지원: 링크에 시간 범위 매개변수를 추가합니다(from=now-1h&to=now).
    • 사용자 지정 매개변수: 대시보드 변수나 새로 고침 간격과 같은 추가 쿼리 매개변수를 포함합니다.

주석

  • 주석 가져오기: 필터를 사용해 주석을 조회합니다. 시간 범위, 대시보드 UID, 태그, 일치 모드를 지원합니다.
  • 주석 생성: 대시보드 또는 패널에 새 주석을 생성합니다.
  • Graphite 주석 생성: Graphite 형식(what, when, tags, data)을 사용해 주석을 생성합니다.
  • 주석 업데이트: 기존 주석의 모든 필드를 교체합니다(전체 업데이트).
  • 주석 패치: 주석의 특정 필드만 업데이트합니다(부분 업데이트).
  • 주석 삭제: ID로 주석을 영구 삭제합니다.
  • 주석 태그 가져오기: 선택적 필터를 사용해 사용 가능한 주석 태그를 나열합니다.

스냅샷

  • 스냅샷 나열: 선택적 쿼리 및 제한 필터를 사용해 대시보드 스냅샷을 나열합니다.
  • 스냅샷 가져오기: 스냅샷 키로 스냅샷 메타데이터와 대시보드 페이로드를 가져옵니다.
  • 스냅샷 생성: 전체 대시보드 페이로드에서 대시보드 스냅샷을 생성하며, 선택적으로 만료 및 외부 스냅샷 옵션을 지정할 수 있습니다.
  • 스냅샷 삭제: 스냅샷 키로 스냅샷을 삭제합니다.

렌더링

  • 패널 또는 대시보드 이미지 가져오기: Grafana 대시보드 패널 또는 전체 대시보드를 PNG 이미지로 렌더링합니다. 보고서, 알림, 프레젠테이션에 사용할 수 있도록 이미지를 base64 인코딩 데이터로 반환합니다. 기본 크기는 패널의 경우 CSS 픽셀 기준 1000×750, 전체 대시보드의 경우 1200×900이며, 둘 다 배율은 1입니다. Explore의 기본 크기는 배율 1에서 1000×1000입니다. 크기는 이미지 렌더러의 뷰포트 제한을 따릅니다. 크기, 시간 범위, 테마, 배율, 대시보드 변수를 사용자 지정할 수 있습니다. 선택적 provisioningPreview 매개변수를 통해 프로비저닝 저장소 브랜치의 아직 적용되지 않은 대시보드(예: git-sync PR 미리 보기)도 렌더링할 수 있습니다.

프로비저닝

  • 프로비저닝 저장소 나열: 이 Grafana 인스턴스에 구성된 프로비저닝 저장소(예: git-sync 소스)를 나열하고, 각 저장소의 슬러그와 소스 URL, 브랜치, 경로, 동기화 상태, 상태 정보를 반환합니다.
  • 프로비저닝 파일 검증: 지정된 브랜치 또는 커밋의 프로비저닝 저장소 파일을 적용하지 않고 시험 실행합니다. 파일의 승인 여부, 리소스 작업(생성/업데이트), 대상 리소스 유형, 구조화된 검증 오류를 반환합니다. 이는 Grafana의 PR 댓글 작성기가 사용하는 것과 동일한 승인 인터페이스입니다.

도구 목록은 구성할 수 있으므로 MCP 클라이언트에서 사용할 도구를 선택할 수 있습니다. 특정 기능을 사용하지 않거나 컨텍스트 창을 너무 많이 차지하지 않도록 하려는 경우 유용합니다. 도구 범주를 비활성화하려면 서버를 시작할 때 --disable-<category> 플래그를 사용하세요. 예를 들어 OnCall 도구를 비활성화하려면 --disable-oncall을 사용하고, 탐색 딥링크 생성을 비활성화하려면 --disable-navigation을 사용하세요.

RBAC 권한

각 도구가 제대로 작동하려면 특정 RBAC 권한이 필요합니다. MCP 서버용 서비스 계정을 생성할 때 사용할 도구에 필요한 권한이 있는지 확인하세요. 나열된 권한은 필요한 최소 작업이며, 사용 사례에 따라 적절한 범위(예: datasources:*, dashboards:*, folders:*)도 필요할 수 있습니다.

팁: Grafana RBAC에 익숙하지 않거나 세분화된 범위를 여러 개 구성하는 대신 더 빠르고 간단하게 설정하려면 서비스 계정에 Editor와 같은 기본 제공 역할을 할당할 수 있습니다. Editor 역할은 대부분의 MCP 서버 작업을 허용하는 광범위한 읽기/쓰기 액세스 권한을 부여합니다. 수동으로 적용하는 범위보다 세분화가 덜 되어(따라서 제한도 덜 엄격하므로) 최소 권한 원칙을 엄격히 지키는 것보다 편의성이 중요한 경우에만 사용하세요.

참고: OnCall 및 기타 플러그인 기반 도구는 grafana-irm-app.schedules:read과 같은 플러그인 작업으로 권한을 확인합니다. 기본 Viewer 역할에는 읽기 작업이, Editor 역할에는 쓰기 작업이 포함됩니다. 인시던트 도구에는 plugins.app:access만 필요하며, IRM은 기본 역할로 인시던트 작업을 승인합니다.

group/resource:verb 형식의 작업(예: dashboard.grafana.app/dashboards:get)은 대리 액세스 토큰에만 적용됩니다. 서비스 계정에는 나머지 나열된 작업만 필요합니다.

Grafana RBAC에 대한 자세한 내용은 공식 문서를 참조하세요.

RBAC 범위

범위는 권한이 적용되는 특정 리소스를 정의합니다. 각 작업에는 적절한 권한과 범위 조합이 모두 필요합니다.

일반적인 범위 패턴:

  • 광범위한 액세스: 조직 전체에 액세스하려면 * 와일드카드를 사용합니다.

    • datasources:* - 모든 데이터 소스에 액세스
    • dashboards:* - 모든 대시보드에 액세스
    • folders:* - 모든 폴더에 액세스
    • teams:* - 모든 팀에 액세스

  • 제한된 액세스: 특정 UID 또는 ID를 사용해 개별 리소스로 액세스를 제한합니다.

    • datasources:uid:prometheus-uid - 특정 Prometheus 데이터 소스에만 액세스
    • dashboards:uid:abc123 - UID가 abc123인 대시보드에만 액세스
    • folders:uid:xyz789 - UID가 xyz789인 폴더에만 액세스
    • teams:id:5 - ID가 5인 팀에만 액세스
    • global.users:id:123 - ID가 123인 사용자에만 액세스

예시:

  • MCP 서버 전체 액세스: 모든 도구에 광범위한 권한을 부여합니다.

    datasources:* (datasources:read, datasources:query)
dashboards:* (dashboards:read, dashboards:create, dashboards:write)
folders:* (for dashboard creation and alert rules)
teams:* (teams:read)
global.users:* (users:read)

  • 제한된 데이터 소스 액세스: 특정 Prometheus 및 Loki 인스턴스만 쿼리합니다.

    datasources:uid:prometheus-prod (datasources:query)
datasources:uid:loki-prod (datasources:query)

  • 대시보드별 액세스: 특정 대시보드만 읽습니다.

    dashboards:uid:monitoring-dashboard (dashboards:read)
dashboards:uid:alerts-dashboard (dashboards:read)

도구

도구범주설명필수 RBAC 권한필수 범위
list_teamsAdmin*모든 팀 나열teams:readteams:* 또는 teams:id:1
list_users_by_orgAdmin*검색 및 페이지네이션을 사용하여 조직의 사용자 나열org.users:readglobal.users:* 또는 global.users:id:123
list_all_rolesAdmin*모든 Grafana 역할 나열roles:readroles:*
get_role_detailsAdmin*Grafana 역할 세부 정보 가져오기roles:readroles:uid:editor
get_role_assignmentsAdmin*역할 할당 나열roles:read, teams.roles:read, users.roles:readroles:uid:editor
list_user_rolesAdmin*사용자 역할 나열users.roles:readglobal.users:id:123
list_team_rolesAdmin*팀 역할 나열teams.roles:readteams:id:7
get_resource_permissionsAdmin*리소스 권한 나열dashboards.permissions:read, datasources.permissions:read, folders.permissions:read, serviceaccounts.permissions:read, teams.permissions:read, users.permissions:readdashboards:uid:abcd1234
get_resource_descriptionAdmin*Grafana 리소스 유형 설명dashboards.permissions:read, datasources.permissions:read, folders.permissions:read, serviceaccounts.permissions:read, teams.permissions:read, users.permissions:readdashboards:*
user_infoUser현재 ID, 기능 및 액세스 가능한 조직None—
search_dashboardsSearch쿼리, 폴더 UID, 폴더 경로, 태그 또는 즐겨찾기 여부로 대시보드 검색dashboards:read, folders:readdashboards:* 또는 dashboards:uid:abc123
search_foldersSearch제목으로 폴더 검색folders:readfolders:* 또는 folders:uid:xyz789
get_dashboard_by_uidDashboardUID로 대시보드 가져오기(선택적으로 저장된 버전 지정)dashboard.grafana.app/dashboards:get, dashboards:read, dashboards:writedashboards:uid:abc123
list_dashboard_versionsDashboard대시보드의 저장된 버전 나열(버전, 작성자, 시간, 메시지)dashboards:read, dashboards:writedashboards:uid:abc123
update_dashboardDashboard대시보드 업데이트 또는 새 대시보드 생성dashboard.grafana.app/dashboards:create, dashboard.grafana.app/dashboards:get, dashboard.grafana.app/dashboards:update, dashboards:create, dashboards:read, dashboards:write, folders:readdashboards:*, folders:* 또는 folders:uid:xyz789
get_dashboard_panel_queriesDashboard대시보드에서 패널 제목, 쿼리, 데이터 소스 UID 및 유형 가져오기dashboard.grafana.app/dashboards:get, dashboards:readdashboards:uid:abc123
run_panel_queryRunPanelQuery*하나 이상의 대시보드 패널 쿼리 실행dashboard.grafana.app/dashboards:get, dashboards:read, datasources:query, datasources:readdashboards:uid:*, datasources:uid:*
get_dashboard_propertyDashboardJSONPath 표현식을 사용하여 대시보드의 특정 부분 추출dashboard.grafana.app/dashboards:get, dashboards:readdashboards:uid:abc123
get_dashboard_summaryDashboard전체 JSON 없이 대시보드의 간결한 요약 가져오기dashboard.grafana.app/dashboards:get, dashboards:readdashboards:uid:abc123
create_folder대시보드폴더 만들기folders:create, folders:read, folders:writefolders:*
list_datasources데이터 소스데이터 소스 목록 조회datasources:readdatasources:*
get_datasource데이터 소스UID 또는 이름으로 데이터 소스 가져오기datasources:readdatasources:uid:prometheus-uid
check_datasources_health데이터 소스하나 이상의 데이터 소스 상태 확인datasources:query, datasources:readdatasources:uid:*
create_datasource데이터 소스데이터 소스 만들기datasources:create, datasources:readdatasources:*
update_datasource데이터 소스데이터 소스 업데이트datasources:read, datasources:writedatasources:* 또는 datasources:uid:abc123
get_query_examples예시*데이터 소스 유형의 예제 쿼리 가져오기없음datasources:*
query_prometheusPrometheus차트를 열지 않고 PromQL을 사용해 메트릭 쿼리datasources:query, datasources:readdatasources:uid:prometheus-uid
render_grafana_app렌더링활성화된 쿼리 도구를 실행하고 대화형 Grafana App에 결과 표시datasources:query, datasources:readdatasources:* 또는 datasources:uid:<uid>
list_prometheus_metric_metadataPrometheus메트릭 메타데이터 목록 조회datasources:query, datasources:readdatasources:uid:prometheus-uid
list_prometheus_metric_namesPrometheus사용 가능한 메트릭 이름 목록 조회datasources:query, datasources:readdatasources:uid:prometheus-uid
list_prometheus_label_namesPrometheus선택자와 일치하는 레이블 이름 목록 조회datasources:query, datasources:readdatasources:uid:prometheus-uid
list_prometheus_label_valuesPrometheus특정 레이블의 값 목록 조회datasources:query, datasources:readdatasources:uid:prometheus-uid
query_prometheus_histogramPrometheus히스토그램 백분위수 값 계산datasources:query, datasources:readdatasources:uid:prometheus-uid
list_incidentsIncidentGrafana Incident의 인시던트 목록 조회(선택적으로 사용자 지정 필드 값 포함)plugins.app:accessN/A
create_incidentIncidentGrafana Incident에서 인시던트 생성(선택적으로 사용자 지정 필드 설정)plugins.app:accessN/A
add_activity_to_incidentIncidentGrafana Incident의 인시던트에 활동 항목 추가plugins.app:accessN/A
update_incidentIncidentGrafana Incident의 인시던트 업데이트(상태, 심각도, 제목 또는 사용자 지정 필드)plugins.app:accessN/A
get_incidentIncidentID로 단일 인시던트 가져오기(사용자 지정 필드 포함)plugins.app:accessN/A
list_incident_custom_fieldsIncident인시던트에 구성된 사용자 지정 필드와 해당 유형 및 선택 옵션 목록 조회plugins.app:accessN/A
query_loki_logsLokiLogQL을 사용해 로그 쿼리 및 검색(로그 쿼리 또는 메트릭 쿼리)datasources:query, datasources:readdatasources:uid:loki-uid
list_loki_label_namesLoki로그에서 사용 가능한 모든 레이블 이름 나열datasources:query, datasources:readdatasources:uid:loki-uid
list_loki_label_valuesLoki특정 로그 레이블의 값 나열datasources:query, datasources:readdatasources:uid:loki-uid
query_loki_statsLoki로그 스트림에 대한 통계 가져오기datasources:query, datasources:readdatasources:uid:loki-uid
query_loki_patternsLoki감지된 로그 패턴을 쿼리하여 공통 구조 식별datasources:query, datasources:readdatasources:uid:loki-uid
analyze_loki_labelsLokiLoki 레이블 전략을 감사하고(실시간 또는 정적) 선택적으로 쿼리 성능 진단datasources:query, datasources:readdatasources:uid:loki-uid
suggest_loki_alloy_label_configConfig승인된 레이블을 적용하는 Alloy loki.process 스니펫 생성NoneN/A
query_influxdbInfluxDB*InfluxQL(v1) 또는 Flux(v2)를 사용하여 InfluxDB 쿼리datasources:query, datasources:readdatasources:uid:influxdb-uid
list_sql_databasesSQL*SQL 데이터 소스의 데이터베이스, 스키마 또는 카탈로그 나열datasources:query, datasources:readdatasources:uid:*
list_sql_tablesSQL*SQL 데이터 소스의 테이블 나열datasources:query, datasources:readdatasources:uid:*
describe_sql_tableSQL*테이블의 열 스키마 가져오기datasources:query, datasources:readdatasources:uid:*
query_sqlSQL*매크로 대체를 사용하여 SQL 쿼리 실행datasources:query, datasources:readdatasources:uid:*
list_cloudwatch_namespacesCloudWatch*사용 가능한 AWS CloudWatch 네임스페이스 나열datasources:query, datasources:readdatasources:uid:*
list_cloudwatch_metricsCloudWatch*네임스페이스의 메트릭 나열datasources:query, datasources:readdatasources:uid:*
list_cloudwatch_dimensionsCloudWatch*메트릭의 차원 나열datasources:query, datasources:readdatasources:uid:*
list_cloudwatch_dimension_valuesCloudWatch*차원 키의 값 나열datasources:query, datasources:readdatasources:uid:*
query_cloudwatchCloudWatch*CloudWatch 메트릭 쿼리 실행datasources:query, datasources:readdatasources:uid:*
list_cloudwatch_log_groupsCloudWatch*CloudWatch 로그 그룹 나열datasources:query, datasources:readdatasources:uid:*
list_cloudwatch_log_group_fieldsCloudWatch*로그 그룹에서 검색된 필드 나열datasources:query, datasources:readdatasources:uid:*
query_cloudwatch_logsCloudWatch*CloudWatch Logs Insights 쿼리 실행datasources:query, datasources:readdatasources:uid:*
list_cloud_logging_projectsCloud Logging*Google Cloud Logging 데이터 소스에서 읽을 수 있는 GCP 프로젝트 나열datasources:query, datasources:readdatasources:uid:*
list_cloud_logging_bucketsCloud Logging*GCP 프로젝트의 로그 버킷 나열datasources:query, datasources:readdatasources:uid:*
list_cloud_logging_viewsCloud Logging*로그 버킷의 로그 뷰 나열datasources:query, datasources:readdatasources:uid:*
query_cloud_loggingCloud Logging*Cloud Logging 쿼리 언어로 로그 쿼리datasources:query, datasources:readdatasources:uid:*
query_elasticsearchElasticsearch/OpenSearch*Lucene 구문 또는 Query DSL을 사용하여 Elasticsearch 또는 OpenSearch 쿼리datasources:query, datasources:readdatasources:uid:datasource-uid
query_quickwitQuickwit*Lucene 구문 또는 Query DSL을 사용하여 Quickwit 쿼리datasources:query, datasources:readdatasources:uid:quickwit-uid
alerting_rules_readAlerting알림 규칙 나열 및 검사(목록, 가져오기, 버전)alert.rules.external:read, alert.rules:read, datasources:read, folders:readfolders:* 또는 folders:uid:alerts-folder
alerting_rules_writeAlertingGrafana 관리 규칙 생성, 업데이트 및 삭제 또는 데이터 소스 관리 규칙 명시적 생성alert.provisioning.provenance:write, alert.rules.external:read, alert.rules.external:write, alert.rules:create, alert.rules:delete, alert.rules:read, alert.rules:write, datasources:read, folders:readfolders:*, 또는 외부 생성의 경우 datasources:uid:<uid>
alerting_manage_routingAlerting알림 정책, 연락 지점 및 시간 간격 관리alert.notifications.external:read, alert.notifications.receivers:read, alert.notifications.routes:read, alert.notifications.time-intervals:read, alert.notifications:read, datasources:query, datasources:read, notifications.alerting.grafana.app/routingtrees:get전역 범위
alerting_routing_writeAlerting기본적으로 Grafana 관리 연락 지점을 생성하거나 외부 Alertmanager 수신기를 명시적으로 생성alert.notifications.external:read, alert.notifications.external:write, alert.notifications.receivers:create, alert.provisioning.provenance:write, datasources:read전역 또는 외부 생성의 경우 datasources:uid:<uid>
alerting_silences_readAlerting알림 무음 나열 및 검사(목록, 가져오기)alert.instances:read, alert.silences:read전역 범위
alerting_silences_writeAlerting알림 무음 생성, 업데이트 및 만료alert.instances:create, alert.instances:read, alert.instances:write, alert.silences:create, alert.silences:read, alert.silences:write전역 범위
list_oncall_schedulesOnCallGrafana OnCall의 일정 나열grafana-irm-app.schedules:read, plugins.app:access플러그인별 범위
get_oncall_shiftOnCall특정 OnCall 교대 근무 세부 정보 가져오기grafana-irm-app.schedules:read, plugins.app:access플러그인별 범위
get_current_oncall_usersOnCall특정 일정에서 현재 온콜 중인 사용자 가져오기grafana-irm-app.schedules:read, grafana-irm-app.user-settings:read, plugins.app:access플러그인별 범위
list_oncall_teamsOnCallGrafana OnCall의 팀 나열grafana-irm-app.user-settings:read, plugins.app:access플러그인별 범위
list_oncall_usersOnCallGrafana OnCall의 사용자 나열grafana-irm-app.user-settings:read, plugins.app:access플러그인별 범위
list_alert_groupsOnCall필터링 옵션을 사용하여 Grafana OnCall의 알림 그룹 나열grafana-irm-app.alert-groups:read, plugins.app:access플러그인별 범위
get_alert_groupOnCallID로 Grafana OnCall의 특정 알림 그룹 가져오기grafana-irm-app.alert-groups:read, plugins.app:access플러그인별 범위
update_alert_groupOnCall알림 그룹 확인, 확인 취소, 해결 또는 해결 취소grafana-irm-app.alert-groups:read, grafana-irm-app.alert-groups:write, plugins.app:access플러그인별 범위
list_pyroscope_label_namesPyroscope선택기와 일치하는 레이블 이름 나열datasources:query, datasources:readdatasources:uid:pyroscope-uid
list_pyroscope_label_valuesPyroscope레이블 이름에 대해 선택기와 일치하는 레이블 값 나열datasources:query, datasources:readdatasources:uid:pyroscope-uid
list_pyroscope_profile_typesPyroscope사용 가능한 프로필 유형 나열datasources:query, datasources:readdatasources:uid:pyroscope-uid
query_pyroscopePyroscopePyroscope에서 프로필, 메트릭 또는 둘 다 쿼리datasources:query, datasources:readdatasources:uid:pyroscope-uid
get_assertions어설션지정된 엔터티의 어설션 요약 가져오기plugins.app:access플러그인별 범위
agento11y_manage_conversationsAgent Observability*Grafana Agent Observability에서 LLM 대화를 나열, 검색 및 가져오기grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access해당 없음
agento11y_manage_generationsAgent Observability*Grafana Agent Observability에서 LLM 생성 세부 정보 및 평가 점수 가져오기grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access해당 없음
agento11y_manage_agentsAgent Observability*에이전트 카탈로그 읽기: 에이전트 나열, 에이전트 버전 전체 정보 가져오기, 버전 기록 나열, 버전별 점수 집계 확인grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access해당 없음
agento11y_manage_evaluatorsAgent Observability*평가기, 평가기 템플릿 및 심사자 카탈로그 관리(나열, 가져오기, 업서트, 포크, 테스트, 삭제)grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access; 쓰기가 활성화된 경우 grafana-agento11y-app.eval:write도 사용해당 없음
agento11y_manage_eval_rulesAgent Observability*평가 규칙 및 가드 관리(나열, 가져오기, 생성, 업데이트, 미리 보기, 삭제)grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access; 쓰기가 활성화된 경우 grafana-agento11y-app.eval:write도 사용해당 없음
agento11y_manage_eval_collectionsAgent Observability*저장된 대화 및 대화를 그룹화하는 컬렉션 관리(나열, 가져오기, 저장, 생성, 업데이트, 삭제, 멤버 추가 및 제거)grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access; 쓰기가 활성화된 경우 grafana-agento11y-app.eval:write도 사용해당 없음
agento11y_manage_experimentsAgent Observability*오프라인 실험, 실험 실행, 점수, 아티팩트 메타데이터 및 필터 패싯 읽기; 실험 업데이트 및 취소grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access; 쓰기가 활성화된 경우 grafana-agento11y-app.eval:write도 사용해당 없음
agento11y_manage_test_suitesAgent Observability*오프라인 실험이 실행되는 테스트 스위트, 해당 버전 및 테스트 사례 관리(나열, 가져오기, 생성, 업데이트, 초안 작성, 게시, 업서트, 삭제)grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access; 쓰기가 활성화된 경우 grafana-agento11y-app.eval:write도 사용해당 없음
ask_assistantAssistant*Grafana Assistant에 프롬프트를 보내고 전체 텍스트 응답 반환(contextId을 통한 다중 턴 대화)grafana-assistant-app.chats:access, plugins.app:access플러그인별 범위
generate_deeplink탐색Grafana 리소스의 정확한 딥링크 URL 생성없음해당 없음
get_annotations주석필터를 사용해 주석 가져오기annotations:readannotations:* 또는 annotations:id:123
create_annotation주석새 주석 생성(표준 또는 Graphite 형식)annotations:createannotations:*
update_annotation주석주석의 특정 필드 업데이트(부분 업데이트)annotations:read, annotations:writeannotations:*
delete_annotation주석ID로 주석 삭제annotations:deleteannotations:*
get_annotation_tags주석선택적 필터링을 사용해 주석 태그 나열annotations:readannotations:*
list_snapshots스냅샷선택적 쿼리 및 제한 필터를 사용해 대시보드 스냅샷 나열snapshots:read해당 없음
get_snapshot스냅샷스냅샷 키로 스냅샷 메타데이터 및 대시보드 페이로드 가져오기없음해당 없음
create_snapshot스냅샷전체 대시보드 페이로드에서 대시보드 스냅샷 생성dashboards:read, snapshots:createdashboards:uid:abc123
delete_snapshot스냅샷스냅샷 키로 대시보드 스냅샷 삭제dashboards:write, snapshots:deletedashboards:uid:abc123
get_panel_image렌더링저장된 대시보드 또는 패널, 프로비저닝 미리 보기 또는 임시 Explore 뷰를 PNG 이미지로 렌더링dashboards:read, datasources:explore, datasources:query, datasources:read, provisioning.repositories:readdashboards:uid:abc123
list_provisioning_repositories프로비저닝소스 URL, 브랜치, 동기화 상태 및 상태와 함께 프로비저닝 리포지토리(예: git-sync 소스) 나열provisioning.grafana.app/repositories:list, provisioning.repositories:read해당 없음
validate_provisioning_file프로비저닝프로비저닝 저장소의 파일을 드라이런 적용하고 승인 검증 오류를 보고합니다dashboard.grafana.app/dashboards:get, dashboards:read, folder.grafana.app/folders:get, folders:read, provisioning.grafana.app/repositories:get, provisioning.repositories:readN/A
search_docs문서Grafana 문서를 검색하거나 제품 그룹을 나열합니다(제품을 나열하려면 query를 생략하세요)NoneN/A
get_doc문서문서 페이지를 가져옵니다. 제목만 보려면 outline_only를, 범위를 지정해 가져오려면 section을 설정하세요NoneN/A
search_tempo_tracesTempoTraceQL로 트레이스를 검색합니다datasources:query, datasources:readdatasources:uid:tempo-uid
query_tempo_metricsTempoTraceQL로 트레이스에서 메트릭을 계산합니다datasources:query, datasources:readdatasources:uid:tempo-uid
get_tempo_traceTempoID로 트레이스를 가져옵니다datasources:query, datasources:readdatasources:uid:tempo-uid
diff_tempo_tracesTempo두 트레이스를 비교합니다datasources:query, datasources:readdatasources:uid:tempo-uid
list_tempo_attribute_namesTempo스팬 및 리소스 속성 이름을 나열합니다datasources:query, datasources:readdatasources:uid:tempo-uid
list_tempo_attribute_valuesTempo트레이스 속성의 값을 나열합니다datasources:query, datasources:readdatasources:uid:tempo-uid
get_tempo_traceql_docsTempoTraceQL 문서를 가져옵니다NoneN/A
query_graphiteGraphite*Graphite 메트릭을 쿼리합니다datasources:query, datasources:readdatasources:uid:graphite-uid
query_graphite_densityGraphite*Graphite 메트릭 밀도를 쿼리합니다datasources:query, datasources:readdatasources:uid:graphite-uid
list_graphite_metricsGraphite*Graphite 메트릭을 나열합니다datasources:query, datasources:readdatasources:uid:graphite-uid
list_graphite_tagsGraphite*Graphite 태그를 나열합니다datasources:query, datasources:readdatasources:uid:graphite-uid
get_plugin플러그인설치된 플러그인을 가져옵니다plugins.app:accessN/A
search_plugin_information플러그인grafana.com 플러그인 카탈로그를 검색합니다NoneN/A
install_plugin플러그인플러그인을 설치합니다plugins:installN/A
grafana_api_requestAPIGrafana HTTP API 엔드포인트를 호출합니다None엔드포인트에 따라 다름
* 기본적으로 비활성화되어 있습니다. 활성화하려면 --enabled-tools에 카테고리를 추가하세요.

render_grafana_app 도구는 렌더링 및 해당 쿼리 카테고리가 활성화된 경우 호환되는 MCP 호스트에 메트릭과 트레이스를 표시합니다. 소스 쿼리 도구는 분석을 위한 텍스트와 구조화된 데이터를 반환합니다. 설정 및 라이브러리 임베딩은 MCP Apps를 참조하세요.

CLI 플래그 참조

mcp-grafana 바이너리는 구성을 위한 다양한 명령줄 플래그를 지원합니다.

전송 옵션:

  • -t, --transport: 전송 유형(stdio, sse 또는 streamable-http) - 기본값: stdio
  • --address: SSE/streamable-http 서버의 호스트 및 포트 - 기본값: localhost:8000
  • --base-path: SSE/streamable-http 서버의 기본 경로. /healthz 및 /metrics은 이 접두사 아래가 아니라 항상 서버 루트에서 제공됩니다. 이 엔드포인트는 프로브와 스크레이퍼를 위한 내부 전용 엔드포인트이며, 애플리케이션 접두사에서 제외하면 리버스 프록시를 통해 API를 노출하면서 이 엔드포인트까지 함께 노출하지 않아도 됩니다.
  • --endpoint-path: streamable-http 서버의 엔드포인트 경로. --base-path 뒤에 추가됩니다 - 기본값: /mcp
  • --sse-keepalive: 각 SSE 클라이언트에 전송되는 핑 요청 간격입니다. 이를 통해 리버스 프록시와 로드 밸런서가 유휴 이벤트 스트림을 닫아 세션이 종료되는 것을 방지합니다. 프록시의 유휴 시간 제한보다 짧게 설정하세요. 예를 들어 ingress-nginx의 기본 60s proxy-read-timeout 뒤에서는 30s을 사용합니다. 핑에 연속 3회 응답하지 않으면 클라이언트 연결이 끊기며, 각 핑의 응답 대기 시간은 간격의 절반입니다. Go duration 문자열을 허용하며, 최소값은 1s입니다 - 기본값: 0 (비활성화됨). --transport sse에만 적용됩니다.
  • --server-name: MCP 핸드셰이크 및 OTel service.name에 사용되는 서버 이름 - 기본값: mcp-grafana. GRAFANA_MCP_SERVER_NAME 환경 변수를 재정의합니다.
  • --instructions-append: 초기화 시 MCP 클라이언트에 반환되는 서버 지침에 추가되는 텍스트입니다. 따라서 연결하는 모든 에이전트가 이 텍스트를 확인할 수 있습니다.

--address에서 포트 0을 사용하면 운영 체제가 사용 가능한 포트를 할당하고 서버는 바인딩된 주소를 작업 디렉터리의 mcp-grafana-address에 원자적으로 기록합니다. 파일은 모드 0600로 생성됩니다.

[!NOTE] SSE에서는 요청별 헤더가 도구 호출에 전달되지 않습니다. X-Grafana-Service-Account-Token / X-Grafana-API-Key, X-Grafana-Org-Id 및 GRAFANA_FORWARD_HEADERS에 나열된 헤더는 아무런 효과가 없으며, 도구 호출은 서버의 환경 자격 증명을 사용하고 X-Grafana-URL 재정의도 작동하지 않습니다. 호출자마다 다른 Grafana URL, 자격 증명 또는 조직이 필요한 경우 streamable-http를 사용하세요.

HTTP 전송 보안(SSE / streamable-http 전용):

Host/Origin 검증은 MCP 리스너의 모든 경로에 적용됩니다. /sse, /mcp 및 동일한 리스너를 공유하는 경우의 /healthz / /metrics도 포함됩니다. 따라서 DNS 리바인딩을 이용하는 브라우저가 이 경로에 접근할 수 없습니다. Stdio 전송에는 영향을 주지 않습니다. --healthz-address 및 --metrics-address는 별도의 리스너를 시작하며, 이 리스너에는 검증이 적용되지 않습니다.

  • --allowed-hosts: Host 헤더 값의 쉼표로 구분된 허용 목록입니다. 기본값은 --address의 루프백 변형입니다(예: localhost:8000,127.0.0.1:8000,[::1]:8000). 파싱 결과가 비어 있으면(설정되지 않음, ,, , 등) 기본값으로 대체되므로 오타로 인해 검사가 조용히 비활성화되지 않습니다. 허용 목록에 없는 Host 헤더가 포함된 요청은 403으로 거부됩니다. Host 검사를 비활성화하려면 *을 전달하세요. 신뢰할 수 있는 리버스 프록시가 Host을 검증하는 경우에만 안전합니다. K8s httpGet 프로브와 외부 /metrics 스크레이프에는 이 목록에 명시적 호스트 이름을 추가하거나, *, tcpSocket 프로브 또는 별도 포트(--healthz-address / --metrics-address)가 필요합니다.
  • --allowed-origins: Origin 헤더 값의 쉼표로 구분된 허용 목록입니다. 기본값은 비어 있습니다. Origin 헤더가 포함된 요청은 모두 거부됩니다(브라우저는 교차 출처 요청에 항상 이 헤더를 보내며, 브라우저가 이 서버를 직접 호출해서는 안 됩니다). 브라우저 기반 클라이언트를 허용하려면 명시적 목록을 설정하거나, 검사를 비활성화하려면 *을 설정하세요.
  • --allow-grafana-url-override: X-Grafana-URL 선택을 활성화합니다. GRAFANA_ALLOW_URL_OVERRIDE으로 대체됩니다. 기본적으로 비활성화되어 있습니다. 허용 목록이 없으면 호출자가 서버에서 접근할 수 있는 모든 HTTP(S) URL을 선택할 수 있습니다.
  • --allowed-grafana-urls: URL 재정의를 위한 선택적 쉼표 구분 Grafana 기본 URL 정확 일치 허용 목록입니다. GRAFANA_ALLOWED_URLS으로 대체됩니다. --allow-grafana-url-override가 필요하며, 명시적으로 빈 플래그를 지정하면 상속된 목록이 비활성화됩니다.

호출자 인증(SSE / streamable-http 전용):

선택적으로 MCP 클라이언트가 서버에 인증하도록 요구할 수 있습니다. 이는 서버가 Grafana에 연결할 때 사용하는 자격 증명과 별개입니다. Stdio에는 영향을 주지 않습니다.

  • --server-auth-token: 호출자가 Authorization: Bearer <token>로 전송해야 하는 베어러 토큰입니다. MCP_GRAFANA_SERVER_TOKEN 환경 변수로 대체됩니다. 설정하면 유효한 토큰이 없는 요청은 도구가 실행되기 전에 401으로 거부됩니다. 프로세스 인수에 비밀이 노출되지 않도록 환경 변수를 사용하는 것이 좋습니다.

호출자 인증은 --server-auth-token가 설정된 경우에만 적용됩니다. 설정되지 않은 상태에서 서버가 루프백이 아닌 주소에 바인딩되면 서버는 시작되지만 보안 오류를 기록합니다. 이 오류는 --log-level에 의해 숨겨지지 않도록 error 로그 수준으로 출력됩니다(루프백 및 stdio에는 영향을 주지 않음). 향후 메이저 릴리스에서는 이 상황이 시작 오류로 처리됩니다. 루프백이 아닌 주소에서 호출자 인증을 활성화할 때는 TLS(또는 TLS 종료)를 사용하세요. 호출자 인증이 활성화되면 검증된 Authorization 헤더는 요청이 Grafana에 전달되기 전에 제거됩니다. --server-auth-token과 GRAFANA_FORWARD_HEADERS=Authorization를 함께 사용하면 시작 시 거부됩니다.

Grafana URL 재정의(streamable-http 전용):

[!WARNING] URL 재정의를 사용하면 MCP 호출자가 아웃바운드 HTTP(S) 대상을 선택할 수 있습니다. 허용 목록은 URL을 제한하지만 호출자를 인증하거나 토큰을 대상에 연결하지는 않습니다.

각 대상을 승인하고, 클라이언트가 제공한 URL 및 토큰 헤더를 교체하며, 일치하는 토큰을 제공하는 인증 프록시 뒤에 배포하세요. 서버의 아웃바운드 네트워크 접근을 승인된 대상으로 제한하세요.

허용 목록이 없으면 가짜 요청 토큰으로 인해 내부 서비스와 메타데이터 서비스를 포함해 접근 가능한 모든 HTTP(S) 서비스로 요청이 전송될 수 있습니다.

대규모 플릿에서 선택 기능을 활성화하려면 GRAFANA_ALLOW_URL_OVERRIDE=true(또는 --allow-grafana-url-override)을 설정하세요. 대상을 제한하려면 GRAFANA_ALLOWED_URLS=https://one.example.com,https://two.example.com/grafana(또는 --allowed-grafana-urls)도 설정하세요.

대상을 선택하는 각 MCP 요청에 다음 헤더를 전송하세요.

X-Grafana-URL: https://one.example.com
X-Grafana-Service-Account-Token: <token for one.example.com>

--server-auth-token가 구성된 경우 Authorization: Bearer <MCP caller token>도 전송하세요. 이 헤더는 MCP 서버에 인증하는 용도이며, 선택한 Grafana 인스턴스에 사용하는 X-Grafana-Service-Account-Token과는 별개입니다. 프록시는 각 인스턴스에 서로 다른 Grafana 토큰을 전송할 수 있으며, 서버는 구성된 토큰 하나를 여러 인스턴스에 공유하지 않습니다. 더 이상 사용되지 않는 X-Grafana-API-Key 헤더도 사용할 수 있습니다. 요청 Grafana 토큰 없이 URL 헤더를 보내면 거부됩니다. 토큰이 포함된 요청을 전송하므로 수신 요청에는 TLS를 사용하세요.

허용 목록은 스킴, 포트, 경로를 포함한 기본 URL 전체가 정확히 일치해야 합니다. 와일드카드는 지원되지 않습니다. Grafana 인증은 SSRF 방어 수단이 아닙니다.

선택한 URL에 대해서는 서버가 GRAFANA_SERVICE_ACCOUNT_TOKEN, GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE, GRAFANA_API_KEY, 환경 기본 인증, GRAFANA_EXTRA_HEADERS 또는 클라이언트 인증서를 사용하지 않습니다. --tls-skip-verify가 설정되어 있어도 TLS 검증은 계속 활성화되며, 구성된 CA 파일도 계속 적용됩니다. 해당 요청에서 명시적으로 전달된 헤더는 계속 적용됩니다. 선택한 기본 URL을 벗어나는 리디렉션 및 기타 Grafana API 요청은 차단됩니다. X-Grafana-URL이 없는 요청에는 일반적인 GRAFANA_URL 및 환경 자격 증명 동작이 유지됩니다. 이 옵션은 streamable HTTP에만 적용됩니다. 요청별 헤더를 도구 호출에 전달하지 않는 SSE에서는 작동하지 않습니다. 따라서 SSE에서 선택한 URL은 호출자의 토큰 없이 사용되어 호출이 실패합니다.

디버그 및 로깅:

  • --debug: 자세한 HTTP 요청/응답 로깅을 위해 디버그 모드를 활성화합니다.
  • --log-level: 로그 수준(debug, info, warn, error) - 기본값: info

Grafana 클라이언트 옵션:

  • --grafana-timeout: Grafana 클라이언트 요청의 시간 제한입니다. Go duration 문자열을 허용합니다(예: 10s, 500ms) - 기본값: 30s
  • --allow-cross-origin-redirects: 아웃바운드 Grafana 클라이언트가 스킴, 호스트 또는 포트가 다른 대상으로 리디렉션을 따르도록 허용합니다. 기본값은 false이며, GRAFANA_ALLOW_CROSS_ORIGIN_REDIRECTS이 환경 변수 대체값입니다. 활성화하면 Grafana 자격 증명이 리디렉션 대상으로 전송될 수 있습니다. 요청에서 선택한 Grafana URL은 선택된 대상으로 고정됩니다.
  • --include-args-in-spans: OpenTelemetry 스팬에 도구 호출 인수를 포함합니다. 프로덕션 환경이 아니거나 인수에 PII가 포함되지 않는다고 확인된 경우에만 활성화하세요 - 기본값: false

관측성:

  • --metrics: /metrics에서 Prometheus 메트릭 엔드포인트를 활성화합니다.
  • --metrics-address: 메트릭 서버의 별도 주소(예: :9090). 비어 있으면 메트릭은 기본 서버에서 제공됩니다.
  • --healthz-address: /healthz의 별도 주소(예: :8080). 비어 있으면 /healthz은 기본 서버에서 제공됩니다. 두 주소가 같으면 --metrics-address과 리스너를 공유합니다. 보조 리스너에는 Host/Origin 검증이 적용되지 않습니다.
  • --slow-request-threshold: MCP 요청(도구 호출, 목록 조회, 리소스 읽기 등)이 이 시간보다 오래 걸리면 이벤트를 기록합니다. Go duration 문자열을 허용합니다(예: 500ms, 5s). 기본값 0은 느린 요청 로깅을 비활성화합니다. 느린 요청 로깅 섹션을 참조하세요.
  • --slow-request-log-level: 느린 요청 이벤트의 로그 수준(info 또는 warn) - 기본값: warn

익명 사용 통계:

  • --usage-stats: 익명 사용 통계 보고: enabled, disabled 또는 log(전송될 보고서를 stderr에 출력하고 아무것도 전송하지 않음). GRAFANA_USAGE_STATS 환경 변수를 재정의하며, 해당 환경 변수는 다시 DO_NOT_TRACK를 재정의합니다. 인식할 수 없는 값은 보고를 비활성화합니다. 익명 사용 통계 섹션을 참조하세요. 도구 구성:

  • --enabled-tools: 활성화된 카테고리의 쉼표로 구분된 목록 - 기본값: admin, agento11y, assistant, athena, clickhouse, cloudlogging, cloudwatch, dsquery, elasticsearch, examples, graphite, quickwit, runpanelquery, snowflake을 제외한 모든 카테고리. 비활성화된 카테고리를 활성화하려면 목록에 추가합니다(예: "search,datasource,...,snowflake").

  • --max-loki-log-limit: query_loki_logs 호출당 반환되는 최대 로그 줄 수 - 기본값: 100. 참고: 잘림을 감지할 수 있도록 Loki의 서버 측 max_entries_limit_per_query보다 최소 1 낮게 설정하세요(도구는 추가 데이터가 있는지 감지하기 위해 내부적으로 limit+1을 요청합니다).

  • --loki-guardrail-mode: query_loki_logs에 대한 Loki 쿼리 비용 보호 장치 - 기본값: off. Loki는 줄 필터가 없는 로그 쿼리에 max_query_bytes_read을 적용하지 않으므로, 넓은 범위의 광범위한 선택자는 테라바이트 단위의 데이터를 스캔할 수 있습니다. 보호 장치는 선택성이 높은 스트림 선택자를 요구하고, 유효 시간 범위(예: [30d]과 같은 범위 벡터 기간 포함)를 제한하며, 쿼리를 실행하기 전에 Loki의 인덱스/통계 바이트 추정치를 사전 확인합니다. shadow은 차단될 쿼리를 기록하지만 실행은 허용합니다(인덱스/통계 왕복 비용은 여전히 발생합니다). enforce은 LLM이 적용할 수 있는 쿼리 수정 안내와 함께 해당 쿼리를 거부합니다. VictoriaLogs에서는 선택자 형태({...})의 쿼리에만 보호 장치가 적용됩니다. 선택자가 파싱되지 않으면(일반적인 중괄호 없는 LogsQL 형태) 쿼리가 그대로 통과하며, 바이트 예산 검사도 적용되지 않습니다(저렴한 인덱스 추정치가 없음). 환경 변수 대체값: GRAFANA_LOKI_GUARDRAIL_MODE.

  • --loki-guardrail-max-bytes: Loki의 인덱스/통계 API를 통해 추정한 단일 query_loki_logs 호출의 최대 스캔 바이트 - 기본값: 107374182400(100 GiB). 0은 바이트 예산 검사를 비활성화합니다. 환경 변수 대체값: GRAFANA_LOKI_GUARDRAIL_MAX_BYTES.

  • --loki-guardrail-max-range: 범위 벡터 기간을 포함한 단일 query_loki_logs 호출의 최대 유효 시간 범위 - 기본값: 24h. Go 기간 문자열을 허용합니다. 0은 범위 검사를 비활성화합니다. 환경 변수 대체값: GRAFANA_LOKI_GUARDRAIL_MAX_RANGE.

  • --prometheus-guardrail-mode: query_prometheus, query_prometheus_histogram 및 run_panel_query의 Prometheus 쿼리에 대한 Prometheus 쿼리 보호 장치 - 기본값: off. 보호 장치는 쿼리가 데이터 소스에 도달하기 전에 쿼리의 유효 시간 범위와 요청하는 시리즈당 포인트 수를 제한합니다. 별도로 선택적으로 활성화할 수 있는 선택자 정책을 통해 모든 벡터 선택자에서 메트릭 이름 외에 비어 있지 않은 양수 레이블 제약 조건을 요구할 수 있습니다. 예시와 제한 사항은 선택자 정책을 참조하세요. shadow은 차단될 쿼리를 기록하지만 실행은 허용합니다. enforce은 LLM이 적용할 수 있는 쿼리 수정 안내와 함께 해당 쿼리를 거부합니다(run_panel_query은 해당 패널의 결과에서 errors 항목으로 이를 보고합니다). 환경 변수 대체값: GRAFANA_PROMETHEUS_GUARDRAIL_MODE.

  • --prometheus-guardrail-require-selective-labels: 각 벡터 선택자에 메트릭 이름 외에 비어 있지 않은 양수 레이블 제약 조건을 포함하도록 요구합니다. 기본값: false; 범위 및 포인트 예산과는 독립적이며, 둘 다 0인 경우에도 적용됩니다. 보호 장치 모드가 off이 아닐 때만 적용됩니다. 환경 변수 대체값: GRAFANA_PROMETHEUS_GUARDRAIL_REQUIRE_SELECTIVE_LABELS. false을 포함한 명시적 CLI 값은 환경 변수보다 우선합니다.

  • --prometheus-guardrail-max-range: 단일 PromQL 쿼리의 최대 유효 시간 범위 - 기본값: 192h. 유효 범위는 쿼리 자체의 시간 범위(즉시 쿼리의 경우 0)에 표현식에서 가장 긴 범위 벡터 또는 하위 쿼리 창을 더한 값입니다. 중첩된 하위 쿼리 범위는 합산되므로 max_over_time(rate(x[5m])[30d:1m])은 30d5m으로 읽힙니다. Go 기간 문자열을 허용하므로 8d이 아니라 192h으로 작성하세요. 0은 범위 검사를 비활성화합니다. 환경 변수 대체값: GRAFANA_PROMETHEUS_GUARDRAIL_MAX_RANGE.

  • --prometheus-guardrail-max-points: 범위 쿼리가 요청할 수 있는 시리즈당 최대 포인트 수, floor(range / step) + 1 - 기본값: 11000, Prometheus 자체의 시리즈당 제한입니다. 안내에는 조건을 충족하는 가장 작은 stepSeconds이 명시됩니다. 0은 포인트 검사를 비활성화합니다. 환경 변수 대체값: GRAFANA_PROMETHEUS_GUARDRAIL_MAX_POINTS.

  • --prometheus-guardrail-max-metric-cardinality: 선택적으로 활성화하는 TSDB 범위 정책. 기본값: 0(비활성화됨). 위 시리즈 수 임계값을 초과하는 정확한 메트릭 이름에는 구성된 범위 레이블에 대한 비어 있지 않은 정확 일치자가 필요합니다. 모드가 off이 아닐 때만 활성화됩니다. 환경 변수 대체값: GRAFANA_PROMETHEUS_GUARDRAIL_MAX_METRIC_CARDINALITY.

  • --prometheus-guardrail-cardinality-cache-ttl: 캐시된 TSDB 스냅샷의 수명. 기본값: 10m; 0도 10m을 사용합니다. 환경 변수 대체값: GRAFANA_PROMETHEUS_GUARDRAIL_CARDINALITY_CACHE_TTL.

  • --prometheus-guardrail-cardinality-scope-labels: 카디널리티 정책을 충족하는 비어 있지 않은 정확 일치자에 사용할 레이블의 쉼표로 구분된 목록. 기본값: job,instance,namespace,pod,service,cluster; 비어 있으면 이 기본값을 사용합니다. __name__은 허용되지 않습니다. 환경 변수 대체값: GRAFANA_PROMETHEUS_GUARDRAIL_CARDINALITY_SCOPE_LABELS. 명시적 CLI 설정은 해당 환경 변수보다 우선합니다.

    Prometheus 보호 장치의 제한 사항: 포인트 검사는 요청된 해상도에 대한 예산을 설정할 뿐, 시리즈, 샘플 또는 하위 쿼리 평가 횟수는 제한하지 않습니다. 또한 Grafana가 범위를 정렬하거나 단계 간격을 늘릴 수 있습니다. offset 및 @ 수정자는 무시됩니다. $__rate_interval 및 $__range과 같은 Grafana 매크로는 표현식을 측정하기 전에 Grafana가 사용하는 값으로 채워집니다($__rate_interval은 단계 간격의 네 배입니다). 보호 장치가 여전히 파싱할 수 없는 표현식(예: $window과 같은 대시보드 변수가 포함된 표현식 또는 다른 방언에서만 허용되는 구문)은 쿼리 자체의 시간 범위와 단계 간격만 검사하며, 그 외에는 실행됩니다. run_panel_query에는 단계 간격 매개변수가 없으므로, Grafana와 마찬가지로 긴 범위에서 1분 단계 간격을 늘려 11000포인트 이내로 유지하거나, enforce 모드에서는 더 낮은 --prometheus-guardrail-max-points 이내로 유지합니다.

  • --prometheus-enforced-matchers: 읽을 수 있는 시리즈를 제한하기 위해 모든 기본 Prometheus 쿼리에 AND로 결합되는 PromQL 레이블 일치자(예: environment=~"prod|staging"). --disable-api이 필요합니다. Prometheus 쿼리 적용을 참조하세요.

  • --loki-enforced-matchers: 읽을 수 있는 로그 스트림을 제한하기 위해 모든 기본 Loki 쿼리에 AND로 결합되는 LogQL 레이블 일치자(예: environment=~"prod|staging"). --disable-api가 필요합니다. Loki 쿼리 적용을 참조하세요.

  • --loki-label-enumeration-fallback: 음수 강제 일치자로 범위를 제한할 수 없을 때 레이블 열거 도구가 수행할 동작: reject(기본값) 또는 unfiltered. Loki 쿼리 적용을 참조하세요.

  • --dashboard-schema: Grafana가 대시보드 스키마 v2를 제공할 때 새 대시보드를 생성하는 클래식 v1(panels[]) 본문을 update_dashboard이 거부하도록 하려면 v2로 설정합니다. 오류에는 재시도에 사용할 최소 v2 본문이 포함됩니다. 기존 v1 대시보드는 계속 편집할 수 있으며, v2를 지원하지 않는 Grafana에는 영향을 주지 않습니다. 기본값: 비어 있음(변경 없음). 환경 변수 대체값: GRAFANA_DASHBOARD_SCHEMA.

  • --disable-search: 검색 도구 비활성화

  • --disable-datasource: 데이터 소스 도구 비활성화

  • --disable-incident: 인시던트 도구 비활성화

  • --disable-prometheus: Prometheus 도구 비활성화

  • --disable-write: 쓰기 도구(생성/업데이트 작업) 비활성화

  • --disable-query: 쿼리 도구(데이터 소스에 대해 쿼리를 실행하는 도구) 비활성화. 메타데이터 및 검색 도구는 계속 사용할 수 있습니다.

  • --enable-query: --disable-write에서도 원시 SQL 쿼리 도구(query_sql, query_influxdb)를 등록된 상태로 유지하고, render_grafana_app의 소스인 query_datasource도 사용할 수 있도록 합니다. 원시 SQL 도구의 경우 --enable-write-tools=query_sql,query_influxdb과 동일한 기능이며, 자주 사용하는 경우를 위한 약칭으로 제공됩니다.

  • --enable-write-tools: --disable-write에서도 등록된 상태로 유지할 개별 도구 이름의 쉼표로 구분된 목록입니다. 쓰기 동작의 범위가 충분히 제한되어 개별적으로 다시 활성화할 수 있는 도구에 사용합니다. 전체 카테고리가 비활성화된 도구에는 영향을 주지 않습니다. 예를 들어 --enable-write-tools=generate_deeplink은 --disable-write에서도 URL 단축(shorten=true)을 사용할 수 있게 하고, --enable-write-tools=alerting_rules_write은 다른 쓰기 도구를 활성화하지 않고도 알림 규칙을 변경할 수 있게 합니다.

  • --disable-loki: Loki 도구 비활성화

  • --disable-elasticsearch: Elasticsearch 및 OpenSearch 도구 비활성화

  • --disable-quickwit: Quickwit 도구 비활성화

  • --disable-influxdb: InfluxDB 도구 비활성화

  • --disable-alerting: 알림 도구 비활성화

  • --disable-dashboard: 대시보드 도구 비활성화

  • --disable-oncall: OnCall 도구 비활성화

  • --disable-asserts: asserts 도구 비활성화

  • --disable-admin: 관리자 도구 비활성화

  • --disable-pyroscope: Pyroscope 도구 비활성화

  • --disable-navigation: 탐색 도구 비활성화

  • --disable-rendering: 렌더링 도구(패널/대시보드 이미지 내보내기) 비활성화

  • --disable-snapshot: 스냅샷 도구 비활성화

  • --disable-cloudwatch: CloudWatch 도구 비활성화

  • --disable-cloudlogging: Google Cloud Logging 도구 비활성화

  • --disable-examples: 쿼리 예시 도구 비활성화

  • --disable-sql: SQL 데이터 소스 도구(ClickHouse, Snowflake, Athena, MySQL, PostgreSQL, MSSQL, BigQuery) 비활성화. 별칭 --disable-clickhouse, --disable-snowflake, --disable-athena도 사용할 수 있습니다.

  • --disable-runpanelquery: 패널 쿼리 실행 도구 비활성화

  • --disable-graphite: Graphite 도구 비활성화

  • --disable-dsquery: render_grafana_app의 query_datasource 소스 비활성화

  • --disable-provisioning: 프로비저닝 도구 비활성화

  • --disable-agento11y: Agent Observability 도구 비활성화

  • --disable-assistant: Grafana Assistant 도구 비활성화

  • --disable-docs: 문서 도구 비활성화

읽기 전용 모드

--disable-write 플래그를 사용하면 MCP 서버를 읽기 전용 모드로 실행하여 Grafana 인스턴스에 대한 모든 쓰기 작업을 방지할 수 있습니다. 다음과 같이 안전한 읽기 전용 액세스를 제공하려는 경우 유용합니다.

  • 읽기 전용 권한이 제한된 서비스 계정 사용
  • 수정 기능 없이 AI 어시스턴트에 관측성 데이터 제공
  • 쓰기 액세스를 제한해야 하는 프로덕션 환경에서 실행
  • 실수로 인한 수정을 방지하려는 테스트 및 개발 시나리오

--disable-write을 활성화하면 다음 쓰기 작업이 비활성화됩니다.

대시보드 도구:

  • update_dashboard

폴더 도구:

  • create_folder

인시던트 도구:

  • create_incident
  • add_activity_to_incident
  • update_incident

알림 도구:

  • alerting_rules_write(생성, 업데이트, 삭제 작업)
  • alerting_silences_write(생성, 업데이트, 삭제 작업)
  • alerting_routing_write(create_contact_point 작업)

각 알림 쓰기 도구는 --enable-write-tools=<name>을 사용해 개별적으로 유지할 수 있습니다.

OnCall 도구:

  • update_alert_group

주석 도구:

  • create_annotation
  • update_annotation
  • delete_annotation

스냅샷 도구:

  • create_snapshot
  • delete_snapshot

탐색 도구:

  • generate_deeplink(shorten=true은 무시되고 전체 URL이 반환됩니다. URL 단축을 유지하려면 --enable-write-tools=generate_deeplink를 전달하세요.)

원시 SQL 쿼리 도구:

이 도구는 제공된 쿼리를 검사하지 않고 그대로 실행하므로 데이터 소스 자격 증명이 허용하는 경우 쓰기 작업을 수행할 수 있습니다. query_sql은 DROP TABLE을 실행하고, query_influxdb은 DELETE를 실행합니다. 따라서 읽기 전용 모드에서는 이 도구들이 제거됩니다. 데이터 소스 자격 증명이 읽기 전용임을 알고 있는 경우, 이 도구들을 유지하려면 --enable-query을 전달하세요.

  • query_sql
  • query_influxdb

Agent Observability 도구:

  • agento11y_manage_evaluators(upsert, 삭제, 분기, 평가기 테스트 작업)
  • agento11y_manage_eval_rules(규칙 및 가드 생성, 업데이트, 삭제, 미리보기 작업)
  • agento11y_manage_eval_collections(저장된 대화 저장 및 삭제, 컬렉션 생성·업데이트·삭제, 컬렉션 구성원 추가 및 제거)
  • agento11y_manage_experiments(실험 업데이트 및 취소 작업)
  • agento11y_manage_test_suites(테스트 스위트 생성 및 업데이트, 버전 생성 및 게시, 테스트 사례 upsert 및 삭제)

모든 읽기 작업은 계속 사용할 수 있으므로 대시보드를 조회하고, PromQL/LogQL 쿼리를 실행하고, 리소스를 나열하고, 데이터를 가져올 수 있습니다. 쓰기를 표현할 수 없는 쿼리 언어(PromQL, LogQL, TraceQL, Elasticsearch DSL, Graphite, CloudWatch)는 읽기 전용 모드에서도 쿼리 도구를 유지합니다. 위에 나열된 원시 SQL 도구만 제거됩니다.

쿼리 없는 모드

--disable-query 플래그는 데이터 소스에 쿼리를 실행하는 모든 도구를 제거하고, 메타데이터 및 검색 도구는 그대로 둡니다. 서비스 계정에 datasources:read 권한은 있지만 datasources:query 권한은 없는 경우처럼, 잠재적으로 비용이 많이 들거나 데이터를 노출할 수 있는 쿼리를 실행하지 않고 데이터 소스, 대시보드, 메트릭 이름, 레이블, 테이블 스키마 등 존재하는 항목을 탐색할 수 있는 어시스턴트를 원할 때 유용합니다.

세 가지 쿼리 설정 중 가장 강력하며, --enable-query보다 우선 적용됩니다.

플래그안전한 쿼리 도구 (query_prometheus, query_loki_logs, run_panel_query, …)원시 SQL 쿼리 도구 (query_sql, query_influxdb)
(없음)등록됨등록됨
--disable-write등록됨등록되지 않음
--disable-write --enable-query등록됨등록됨
--disable-query등록되지 않음등록되지 않음
--disable-query --enable-query등록되지 않음등록되지 않음

--disable-query이 활성화되면 다음 도구가 등록되지 않습니다.

Prometheus 도구:

  • query_prometheus
  • query_prometheus_histogram

렌더링 도구:

  • render_grafana_app

Loki 도구:

  • query_loki_logs
  • query_loki_patterns

query_loki_stats 및 analyze_loki_labels은 등록된 상태로 유지됩니다. 둘 다 선택기를 데이터 소스로 보내지만, 로그 내용 대신 인덱스를 읽고 스트림, 청크, 바이트 수를 반환합니다.

Elasticsearch/OpenSearch 및 Quickwit 도구:

  • query_elasticsearch
  • query_quickwit

InfluxDB 도구 (--disable-write에 의해서도 제거됨, 위 참조):

  • query_influxdb

SQL 데이터 소스 도구 (--disable-write에 의해서도 제거됨, 위 참조):

  • query_sql

Graphite 도구:

  • query_graphite
  • query_graphite_density

CloudWatch 도구:

  • query_cloudwatch
  • query_cloudwatch_logs

Google Cloud Logging 도구:

  • query_cloud_logging

Pyroscope 도구:

  • query_pyroscope

패널 쿼리 실행 도구:

  • run_panel_query

elasticsearch, quickwit, influxdb, runpanelquery 카테고리에는 다른 항목이 없으므로 쿼리가 비활성화되면 도구가 전혀 등록되지 않습니다. 다른 모든 카테고리의 관련 도구인 list_prometheus_metric_names, list_loki_label_values, describe_sql_table, list_cloudwatch_metrics, list_cloud_logging_projects 등은 계속 사용할 수 있습니다.

--disable-query은 쿼리 도구와 grafana_api_request의 POST 경로를 /api/ds/query으로 제한하지만, 데이터 소스로 향하는 모든 경로를 통제하지는 않습니다. 읽기 전용 모드에서 grafana_api_request는 쿼리 도구가 활성화된 경우에만 /api/ds/query로의 POST를 허용합니다(원시 SQL 도구와 동일한 제한이며, --disable-write에 의해 차단되고 --enable-query이 재정의하지 않는 한 허용되지 않음). 서버 측에서 패널을 렌더링하는 get_panel_image은 영향을 받지 않습니다.

클라이언트 TLS 구성(Grafana 연결용):

  • --tls-cert-file: 클라이언트 인증에 사용할 TLS 인증서 파일 경로
  • --tls-key-file: 클라이언트 인증에 사용할 TLS 개인 키 파일 경로
  • --tls-ca-file: 서버 확인에 사용할 TLS CA 인증서 파일 경로
  • --tls-skip-verify: TLS 인증서 확인 건너뛰기(안전하지 않음)

서버 TLS 구성(streamable-http 전송 전용):

  • --server.tls-cert-file: 서버 HTTPS용 TLS 인증서 파일 경로
  • --server.tls-key-file: 서버 HTTPS용 TLS 개인 키 파일 경로

사용법

이 MCP 서버는 로컬 Grafana 인스턴스와 Grafana Cloud 모두에서 작동합니다. Grafana Cloud를 사용하는 경우 아래 구성 예시에서 http://localhost:3000 대신 인스턴스 URL(예: https://myinstance.grafana.net)을 사용하세요.

  1. 서비스 계정 토큰 인증을 사용하는 경우, 사용하려는 도구를 사용할 수 있도록 충분한 권한을 가진 서비스 계정을 Grafana에서 만들고, 서비스 계정 토큰을 생성한 다음 구성 파일에 사용할 수 있도록 클립보드에 복사합니다. 서비스 계정 토큰 생성에 대한 자세한 내용은 Grafana 서비스 계정 문서를 참조하세요. 팁: 세분화된 RBAC 범위를 구성하기 어렵다면, 서비스 계정에 기본 제공 Editor 역할을 할당하는 더 간단하지만 제한이 덜한 방법을 사용할 수 있습니다. 이 역할은 대부분의 MCP 서버 작업에 필요한 광범위한 읽기/쓰기 액세스 권한을 부여합니다. 엄격한 최소 권한 요구사항보다 편의성이 중요할 때 사용하세요.

    참고: 환경 변수 GRAFANA_API_KEY은 더 이상 사용되지 않으며 향후 버전에서 제거될 예정입니다. 대신 GRAFANA_SERVICE_ACCOUNT_TOKEN을 사용하도록 마이그레이션하세요. 이전 변수 이름도 하위 호환성을 위해 계속 작동하지만 사용 중단 경고가 표시됩니다.

파일에서 서비스 계정 토큰 읽기

토큰을 GRAFANA_SERVICE_ACCOUNT_TOKEN을 통해 인라인으로 전달하는 대신, 토큰이 들어 있는 파일 경로를 GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE에 지정할 수 있습니다. 파일은 요청이 있을 때마다 새로 읽히므로 서버를 다시 시작하지 않아도 토큰 교체가 자동으로 반영됩니다.

이는 특히 Kubernetes에서 유용합니다. 볼륨으로 마운트된 Secret은 기반 Secret이 변경되면 제자리에서 업데이트됩니다(일반적으로 약 1분 이내). 요청별 클라이언트 캐시(토큰 값을 키로 사용)와 결합하면, 토큰이 교체될 때 파드 재시작이나 다운타임 없이 새 클라이언트가 투명하게 생성됩니다.

env:
  - name: GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE
    value: /var/run/secrets/grafana/token
volumeMounts:
  - name: grafana-token
    mountPath: /var/run/secrets/grafana
    readOnly: true
volumes:
  - name: grafana-token
    secret:
      secretName: grafana-mcp-token

파일 내용의 앞뒤 공백(끝의 줄바꿈 포함)은 제거됩니다. GRAFANA_SERVICE_ACCOUNT_TOKEN와 GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE이 모두 설정된 경우 인라인 토큰이 우선합니다.

다중 조직 지원

다음 방법 중 하나로 상호작용할 조직을 지정할 수 있습니다.

  • 환경 변수: GRAFANA_ORG_ID에 숫자 조직 ID를 설정합니다.
  • HTTP 헤더: streamable HTTP 전송을 사용할 때 X-Grafana-Org-Id를 설정합니다(헤더가 환경 변수보다 우선하므로 기본 조직도 설정할 수 있습니다).

조직 ID가 제공되면 MCP 서버는 Grafana에 보내는 모든 요청에 X-Grafana-Org-Id 헤더를 설정하여 지정된 조직 컨텍스트에서 작업이 수행되도록 합니다.

동적 조직 선택(호출별)

위 옵션은 전체 연결에 사용할 조직을 고정합니다. 단일 연결에서 도구를 호출할 때마다 서로 다른 조직을 대상으로 하려면 --dynamic-multi-org 플래그를 사용해 서버를 시작하세요. 기본적으로 꺼져 있습니다.

활성화하면 모든 도구에서 선택적 orgId 인수를 사용할 수 있습니다. 이 인수는 해당 호출에 한해 연결의 조직을 재정의하며, X-Grafana-Org-Id 헤더와 앱 플랫폼 API의 확인된 Kubernetes 네임스페이스 모두에 적용됩니다. 프록시된 데이터 소스 도구는 자격 증명으로 액세스할 수 있는 모든 조직에서 추가로 검색됩니다. orgId을 생략한 호출은 연결의 기본 조직을 사용합니다.

이 기능은 둘 이상의 조직에 속한 자격 증명(예: 사용자 또는 대리 사용자 ID)에서만 작동합니다. 서비스 계정 토큰은 단일 조직에 계속 바인딩됩니다. 유효한 orgId 값을 확인하려면 user_info 도구를 사용하세요.

조직 ID 사용 예시:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_USERNAME": "<your username>",
        "GRAFANA_PASSWORD": "<your password>",
        "GRAFANA_ORG_ID": "2"
      }
    }
  }
}

사용자 지정 HTTP 헤더

GRAFANA_EXTRA_HEADERS 환경 변수를 사용하여 모든 Grafana API 요청에 임의의 HTTP 헤더를 추가할 수 있습니다. 값은 헤더 이름과 값을 매핑하는 JSON 객체여야 합니다.

사용자 지정 헤더 예시:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your token>",
        "GRAFANA_EXTRA_HEADERS": "{\"X-Custom-Header\": \"custom-value\", \"X-Tenant-ID\": \"tenant-123\"}"
      }
    }
  }
}

SOCKS5 프록시

GRAFANA_SOCKS5_PROXY 환경 변수를 사용하여 이 서버가 Grafana에 보내는 모든 요청을 SOCKS5 프록시를 통해 라우팅할 수 있습니다. 프록시는 이 서버의 Grafana 트래픽에만 적용됩니다. 전역 HTTP_PROXY/HTTPS_PROXY 변수를 수정하지 않으며, 설정된 경우 Grafana 전송에 한해 해당 변수의 프록시 선택을 재정의합니다. 다른 MCP 서버나 셸 세션에는 영향을 주지 않습니다. 설정하지 않으면 동작은 변경되지 않습니다.

URL은 socks5:// 또는 socks5h:// 스킴을 사용해야 합니다(Go에서는 두 스킴을 동일하게 처리하며, 호스트 이름 확인은 프록시에 위임됩니다). 자격 증명을 포함할 수도 있습니다(예: socks5://user:pass@127.0.0.1:1080).

예시:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your token>",
        "GRAFANA_SOCKS5_PROXY": "socks5://127.0.0.1:1080"
      }
    }
  }
}

잘못된 프록시 URL은 시작 오류를 일으킵니다. 프록시 연결을 런타임에 구성하지 못하면 서버는 Grafana 트래픽을 조용히 직접 전송하는 대신 연결을 차단합니다.

클라이언트 헤더 전달(streamable-http 전용)

MCP 서버가 SSO를 처리하는 게이트웨이나 리버스 프록시(예: OIDC를 사용하는 AWS ALB) 뒤에서 실행되는 경우, Grafana가 요청을 인증된 사용자와 연결할 수 있도록 각 사용자의 세션 쿠키를 Grafana에 전달해야 합니다. GRAFANA_FORWARD_HEADERS 환경 변수는 쉼표로 구분된 헤더 이름 허용 목록을 지정하여 이 기능을 활성화합니다. 지정된 헤더는 수신 HTTP 요청에서 모든 아웃바운드 Grafana API 요청으로 복사됩니다.

이 기능은 streamable-http(-t streamable-http) 전송을 사용할 때만 적용됩니다. stdio 또는 SSE 모드에는 영향을 주지 않습니다.

예시: 세션 쿠키 전달

{
  "env": {
    "GRAFANA_URL": "https://grafana.internal",
    "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your token>",
    "GRAFANA_FORWARD_HEADERS": "Cookie"
  }
}

쉼표로 구분하여 여러 헤더를 전달할 수 있습니다.

GRAFANA_FORWARD_HEADERS=Cookie,X-Session-Id

전달된 헤더는 GRAFANA_EXTRA_HEADERS에 정의된 헤더와 병합됩니다. 헤더 이름이 양쪽에 모두 있으면 해당 요청에서는 수신 요청의 값이 우선합니다.

추적 컨텍스트 헤더(traceparent, tracestate, baggage)는 예외입니다. 서버가 추적 컨텍스트를 직접 전파하므로 전달된 값은 서버가 주입하는 값을 재정의하지 않습니다. 자세한 내용은 관측 가능성을 참조하세요.

  1. mcp-grafana을 설치하는 방법은 여러 가지입니다.

    • uvx(권장): uv가 설치되어 있다면 별도의 설정이 필요하지 않습니다. uvx이 서버를 자동으로 다운로드하고 실행합니다.

      uvx mcp-grafana

    • Docker 이미지: Docker Hub에서 사전 빌드된 Docker 이미지를 사용합니다.

      중요: Docker 이미지의 진입점은 기본적으로 MCP 서버를 SSE 모드로 실행하도록 구성되어 있지만, 대부분의 사용자는 Claude Desktop과 같은 AI 어시스턴트와 직접 통합하기 위해 STDIO 모드를 사용해야 합니다.

      1. STDIO 모드: stdio 모드에서는 기본값을 명시적으로 재정의하려면 -t stdio을 사용하고, stdin을 열린 상태로 유지하려면 -i 플래그를 포함해야 합니다.
      docker pull grafana/mcp-grafana
# For local Grafana:
docker run --rm -i -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> grafana/mcp-grafana -t stdio
# For Grafana Cloud:
docker run --rm -i -e GRAFANA_URL=https://myinstance.grafana.net -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> grafana/mcp-grafana -t stdio

      참고 — 네트워크 모드 보안 설정: SSE 및 streamable-http 모드에서 컨테이너는 루프백이 아닌 주소(0.0.0.0:8000)에 바인딩됩니다. 호출자 토큰이 없으면 서버는 시작되지만 보안 오류를 로그에 기록합니다(error 로그 수준이므로 --log-level에 의해 숨겨지지 않으며, 향후 주요 버전에서는 시작이 거부됩니다). 클라이언트에 Authorization: Bearer <token>을 요구하려면 MCP_GRAFANA_SERVER_TOKEN을 설정하세요(권장). STDIO 모드에는 영향을 주지 않습니다. 호출자 인증을 참조하세요.

      1. SSE 모드: 이 모드에서 서버는 클라이언트가 연결하는 HTTP 서버로 실행됩니다. -p 플래그를 사용하여 포트 8000을 노출해야 합니다.
      docker pull grafana/mcp-grafana
docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> -e MCP_GRAFANA_SERVER_TOKEN=<caller auth token> grafana/mcp-grafana
      1. Streamable HTTP 모드: 이 모드에서 서버는 여러 클라이언트 연결을 처리할 수 있는 독립 프로세스로 작동합니다. -p 플래그를 사용하여 포트 8000을 노출해야 합니다. 이 모드에서는 기본값을 명시적으로 재정의하려면 -t streamable-http을 사용해야 합니다.
      docker pull grafana/mcp-grafana
docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> -e MCP_GRAFANA_SERVER_TOKEN=<caller auth token> grafana/mcp-grafana -t streamable-http

      서버 TLS 인증서를 사용하는 HTTPS streamable HTTP 모드의 경우:

      docker pull grafana/mcp-grafana
docker run --rm -p 8443:8443 \
  -v /path/to/certs:/certs:ro \
  -e GRAFANA_URL=http://localhost:3000 \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> \
  -e MCP_GRAFANA_SERVER_TOKEN=<caller auth token> \
  grafana/mcp-grafana \
  -t streamable-http \
  -addr :8443 \
  --server.tls-cert-file /certs/server.crt \
  --server.tls-key-file /certs/server.key

    • 바이너리 다운로드: 릴리스 페이지에서 mcp-grafana의 최신 릴리스를 다운로드하여 $PATH에 배치합니다.

    • 소스에서 빌드: Go 툴체인이 설치되어 있다면 GOBIN 환경 변수를 사용해 소스에서 빌드하고 설치할 수도 있습니다. 이 변수로 바이너리를 설치할 디렉터리를 지정합니다. 이 디렉터리도 $PATH에 있어야 합니다.

      GOBIN="$HOME/go/bin" go install github.com/grafana/mcp-grafana/v2/cmd/mcp-grafana@latest

    • Helm을 사용해 Kubernetes에 배포: Grafana helm-charts 저장소의 Helm 차트를 사용합니다.

      helm repo add grafana https://grafana.github.io/helm-charts
helm install --set grafana.apiKey=<Grafana_ApiKey> --set grafana.url=<GrafanaUrl> my-release grafana/grafana-mcp

  2. 클라이언트 구성 파일에 서버 구성을 추가합니다. 예를 들어 Claude Desktop의 경우:

    uvx를 사용하는 경우:

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

    바이너리를 사용하는 경우:

    {
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",  // Or "https://myinstance.grafana.net" for Grafana Cloud
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>",
        // If using username/password authentication
        "GRAFANA_USERNAME": "<your username>",
        "GRAFANA_PASSWORD": "<your password>",
        // Optional: specify organization ID for multi-org support
        "GRAFANA_ORG_ID": "1"
      }
    }
  }
}

참고: Claude Desktop에서 Error: spawn mcp-grafana ENOENT가 표시되면 mcp-grafana의 전체 경로를 지정해야 합니다.

Docker를 사용하는 경우:

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN",
        "grafana/mcp-grafana",
        "-t",
        "stdio"
      ],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",  // Or "https://myinstance.grafana.net" for Grafana Cloud
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>",
        // If using username/password authentication
        "GRAFANA_USERNAME": "<your username>",
        "GRAFANA_PASSWORD": "<your password>",
        // Optional: specify organization ID for multi-org support
        "GRAFANA_ORG_ID": "1"
      }
    }
  }
}

참고: 여기서 -t stdio 인수는 Docker 이미지의 기본 SSE 모드를 재정의하므로 필수입니다.

원격 MCP 서버에서 VSCode 사용

VSCode를 사용하고 MCP 서버를 SSE 모드로 실행하는 경우(Docker 이미지를 전송 방식을 재정의하지 않고 사용할 때 기본값), .vscode/settings.json에 다음 내용이 포함되어 있는지 확인하세요.

"mcp": {
  "servers": {
    "grafana": {
      "type": "sse",
      "url": "http://localhost:8000/sse"
    }
  }
}

서버 TLS 인증서를 사용하는 HTTPS 스트리밍 가능한 HTTP 모드의 경우:

"mcp": {
  "servers": {
    "grafana": {
      "type": "sse",
      "url": "https://localhost:8443/sse"
    }
  }
}

디버그 모드

명령에 -debug 플래그를 추가하면 Grafana 전송 방식의 디버그 모드를 활성화할 수 있습니다. 그러면 MCP 서버와 Grafana API 간의 HTTP 요청 및 응답이 자세히 기록되어 문제 해결에 도움이 됩니다.

Claude Desktop 구성에서 디버그 모드를 사용하려면 다음과 같이 구성을 업데이트하세요.

바이너리를 사용하는 경우:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": ["-debug"],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",  // Or "https://myinstance.grafana.net" for Grafana Cloud
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

Docker를 사용하는 경우:

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN",
        "grafana/mcp-grafana",
        "-t",
        "stdio",
        "-debug"
      ],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",  // Or "https://myinstance.grafana.net" for Grafana Cloud
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

참고: 표준 구성과 마찬가지로 Docker 이미지의 기본 SSE 모드를 재정의하려면 -t stdio 인수가 필요합니다.

TLS 구성

Grafana 인스턴스가 mTLS 뒤에 있거나 사용자 지정 TLS 인증서가 필요한 경우, MCP 서버가 사용자 지정 인증서를 사용하도록 구성할 수 있습니다. 서버는 다음 TLS 구성 옵션을 지원합니다.

  • --tls-cert-file: 클라이언트 인증에 사용할 TLS 인증서 파일 경로
  • --tls-key-file: 클라이언트 인증에 사용할 TLS 개인 키 파일 경로
  • --tls-ca-file: 서버 확인에 사용할 TLS CA 인증서 파일 경로
  • --tls-skip-verify: TLS 인증서 확인 건너뛰기(안전하지 않으므로 테스트에만 사용)

클라이언트 인증서를 사용한 예:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [
        "--tls-cert-file",
        "/path/to/client.crt",
        "--tls-key-file",
        "/path/to/client.key",
        "--tls-ca-file",
        "/path/to/ca.crt"
      ],
      "env": {
        "GRAFANA_URL": "https://secure-grafana.example.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

Docker 사용 예:

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/path/to/certs:/certs:ro",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN",
        "grafana/mcp-grafana",
        "-t",
        "stdio",
        "--tls-cert-file",
        "/certs/client.crt",
        "--tls-key-file",
        "/certs/client.key",
        "--tls-ca-file",
        "/certs/ca.crt"
      ],
      "env": {
        "GRAFANA_URL": "https://secure-grafana.example.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

TLS 구성은 MCP 서버에서 사용하는 모든 HTTP 클라이언트에 적용됩니다. 여기에는 다음이 포함됩니다.

  • 기본 Grafana OpenAPI 클라이언트
  • Prometheus 데이터 소스 클라이언트
  • Loki 데이터 소스 클라이언트
  • 인시던트 관리 클라이언트
  • 알림 클라이언트
  • Asserts 클라이언트

CLI 직접 사용 예:

자체 서명 인증서로 테스트하는 경우:

./mcp-grafana --tls-skip-verify -debug

클라이언트 인증서를 사용하는 경우:

./mcp-grafana \
  --tls-cert-file /path/to/client.crt \
  --tls-key-file /path/to/client.key \
  --tls-ca-file /path/to/ca.crt \
  -debug

사용자 지정 CA 인증서만 사용하는 경우:

./mcp-grafana --tls-ca-file /path/to/ca.crt

프로그래밍 방식 사용:

이 라이브러리를 프로그래밍 방식으로 사용하는 경우 TLS를 활성화한 컨텍스트 함수도 만들 수 있습니다.

// Using struct literals
tlsConfig := &mcpgrafana.TLSConfig{
    CertFile: "/path/to/client.crt",
    KeyFile:  "/path/to/client.key",
    CAFile:   "/path/to/ca.crt",
}
grafanaConfig := mcpgrafana.GrafanaConfig{
    Debug:     true,
    TLSConfig: tlsConfig,
}
contextFunc := mcpgrafana.ComposedStdioContextFunc(grafanaConfig)

// Or inline
grafanaConfig := mcpgrafana.GrafanaConfig{
    Debug: true,
    TLSConfig: &mcpgrafana.TLSConfig{
        CertFile: "/path/to/client.crt",
        KeyFile:  "/path/to/client.key",
        CAFile:   "/path/to/ca.crt",
    },
}
contextFunc := mcpgrafana.ComposedStdioContextFunc(grafanaConfig)

URL 유효성 검사:

NewGrafanaClient를 직접 호출할 때(stdio 또는 프로그래밍 방식 구성), 복구 가능한 패닉을 방지하려면 URL을 사전 검증하세요.

if err := mcpgrafana.ValidateGrafanaURL(urlFromHeader); err != nil {
    http.Error(w, err.Error(), http.StatusBadRequest)
    return
}
client := mcpgrafana.NewGrafanaClient(ctx, urlFromHeader, apiKey, nil)

서버 TLS 구성(스트리밍 가능한 HTTP 전송 전용)

스트리밍 가능한 HTTP 전송(-t streamable-http)을 사용할 때 MCP 서버가 HTTP 대신 HTTPS를 제공하도록 구성할 수 있습니다. MCP 클라이언트와 서버 자체 간의 연결을 보호해야 하는 경우 유용합니다.

서버는 스트리밍 가능한 HTTP 전송에 대해 다음 TLS 구성 옵션을 지원합니다.

  • --server.tls-cert-file: 서버 HTTPS용 TLS 인증서 파일 경로(TLS에 필수)
  • --server.tls-key-file: 서버 HTTPS용 TLS 개인 키 파일 경로(TLS에 필수)

참고: 이 플래그는 위에 설명된 클라이언트 TLS 플래그와 완전히 별개입니다. 클라이언트 TLS 플래그는 MCP 서버가 Grafana에 연결하는 방식을 구성하고, 서버 TLS 플래그는 스트리밍 가능한 HTTP 전송을 사용할 때 클라이언트가 MCP 서버에 연결하는 방식을 구성합니다.

HTTPS 스트리밍 가능한 HTTP 서버 예:

./mcp-grafana \
  -t streamable-http \
  --server.tls-cert-file /path/to/server.crt \
  --server.tls-key-file /path/to/server.key \
  -addr :8443

이렇게 하면 MCP 서버가 HTTPS 포트 8443에서 시작됩니다. 그러면 클라이언트는 http://localhost:8000/ 대신 https://localhost:8443/에 연결합니다.

서버 TLS를 사용하는 Docker 예:

docker run --rm -p 8443:8443 \
  -v /path/to/certs:/certs:ro \
  -e GRAFANA_URL=http://localhost:3000 \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> \
  grafana/mcp-grafana \
  -t streamable-http \
  -addr :8443 \
  --server.tls-cert-file /certs/server.crt \
  --server.tls-key-file /certs/server.key

상태 확인 엔드포인트

SSE(-t sse) 또는 스트리밍 가능한 HTTP(-t streamable-http) 전송을 사용할 때 MCP 서버는 /healthz에 상태 확인 엔드포인트를 노출합니다. 로드 밸런서, 모니터링 시스템 또는 오케스트레이션 플랫폼에서 이 엔드포인트를 사용해 서버가 실행 중이며 연결을 수락하는지 확인할 수 있습니다.

엔드포인트: GET /healthz

응답:

  • 상태 코드: 200 OK
  • 본문: ok

사용 예:

# For streamable HTTP or SSE transport on default port
curl http://localhost:8000/healthz

# Probe a side listener while MCP stays on loopback (Kubernetes + sidecar)
./mcp-grafana -t streamable-http --address 127.0.0.1:8000 --healthz-address :8080
curl http://127.0.0.1:8080/healthz

# With --base-path /my-base the MCP routes move under the prefix
# (/my-base/sse, /my-base/mcp), but healthz does not:
curl http://localhost:8000/healthz          # 200 ok
curl http://localhost:8000/my-base/healthz  # 404

참고: 상태 확인 엔드포인트는 SSE 또는 스트리밍 가능한 HTTP 전송을 사용할 때만 사용할 수 있습니다. stdio 전송(-t stdio)에서는 HTTP 서버를 노출하지 않으므로 사용할 수 없습니다.

익명 사용 통계

서버는 호출된 도구, 실패한 호출 수, 서버 구성 방식 등 서버 자체에 대한 익명 사용 통계를 Grafana Labs에 보고할 수 있습니다. 보고서 하나는 사용자 한 명이나 대화 하나가 아니라 서버 프로세스 하나를 대상으로 하며, 4시간마다 한 번과 종료 시 한 번 전송됩니다. 보고는 기본적으로 활성화되어 있습니다. 보고를 거부하려면 --usage-stats=disabled, GRAFANA_USAGE_STATS=disabled 또는 DO_NOT_TRACK=1을 설정하세요.

도구 인수, 리소스 이름, 쿼리, 로그 행, 오류 메시지 및 자격 증명은 전송되지 않습니다. 플래그는 이름만 기록되고 값은 기록되지 않으며, Grafana 인스턴스는 cloud 또는 self_hosted로만 표시됩니다. URL, 호스트 이름, 스택 슬러그 또는 조직 정보는 전송되지 않습니다. 사용자별, 세션별 또는 클라이언트별 데이터는 없습니다. 전송되는 세션 식별자가 없으며 특정 클라이언트에 도구 호출을 연결할 방법도 없습니다.

# Turn reporting on
mcp-grafana --usage-stats=enabled

# Turn it off (or GRAFANA_USAGE_STATS=disabled)
mcp-grafana --usage-stats=disabled

# Print what would be sent, to stderr, and send nothing
GRAFANA_USAGE_STATS=log mcp-grafana

DO_NOT_TRACK=1도 도구 간 DO_NOT_TRACK 규칙에 따라 보고를 비활성화합니다. 1만 영향을 미치며 비활성화만 할 수 있습니다. 또한 --usage-stats와 GRAFANA_USAGE_STATS은 이를 재정의하므로, 전역으로 설정하는 호스트도 특정 서버에서 다시 활성화할 수 있습니다.

GRAFANA_USAGE_STATS_ENDPOINT는 전송 대상을 변경합니다. 보고 거부 옵션이 아닙니다.

전체 필드 목록, 전송되지 않는 항목, 데이터 해석 방법 및 제한 사항은 익명 사용 통계를 참조하세요.

관측 가능성

MCP 서버는 OTel MCP 의미 규칙에 따라 Prometheus 메트릭, OpenTelemetry 분산 추적 및 OpenTelemetry 로그 내보내기를 지원합니다. 추적 및 로그 내보내기는 표준 OTEL_* 환경 변수를 통해 구성되며 모든 전송 방식에서 작동합니다.

참고: mcp-grafana는 현재 추적과 로그 모두에 대해 OTLP/gRPC 전송만 지원합니다. OTEL_EXPORTER_OTLP_PROTOCOL(및 해당 _TRACES_PROTOCOL / _LOGS_PROTOCOL 변형)은 적용되지 않으며, 항상 gRPC를 사용합니다.

메트릭

SSE 또는 스트리밍 가능한 HTTP 전송을 사용할 때 --metrics 플래그로 Prometheus 메트릭을 활성화하세요.

# Metrics served on the main server at /metrics
./mcp-grafana -t streamable-http --metrics

# Metrics served on a separate address
./mcp-grafana -t streamable-http --metrics --metrics-address :9090

사용 가능한 메트릭:

메트릭유형설명
mcp_server_operation_duration_seconds히스토그램MCP 작업 소요 시간(레이블: mcp_method_name, gen_ai_tool_name, error_type, network_transport, mcp_protocol_version)
http_server_request_duration_seconds히스토그램HTTP 서버 요청 소요 시간(otelhttp에서 제공)

참고: 메트릭은 SSE 또는 스트리밍 가능한 HTTP 전송을 사용할 때만 사용할 수 있습니다. stdio 전송에서는 사용할 수 없습니다.

Loki 비용 가드레일(--loki-guardrail-mode)이 활성화되면, 가드레일의 결정을 기록하는 카운터 4개가 추가됩니다.

메트릭유형설명
mcp_loki_guardrail_admitted_total카운터활성화된 모든 검사를 통과한 쿼리(레이블: backend)
mcp_loki_guardrail_would_block_total카운터shadow 모드에서 검사에 실패했지만 계속 실행된 쿼리(레이블: backend, reason)
mcp_loki_guardrail_blocked_total카운터enforce 모드에서 거부된 쿼리(레이블: backend, reason)
mcp_loki_guardrail_fail_open_total카운터가드레일이 평가할 수 없어 허용한 쿼리(레이블: backend, cause)

reason은 selector, range, bytes 중 하나입니다. cause는 unparseable, estimate_failed 중 하나이며, backend은 loki, victorialogs, unknown 중 하나입니다. 여러 검사를 위반한 쿼리는 한 번만 집계되며, 가장 먼저 실행된 검사(selector, 그다음 range, 그다음 bytes)를 레이블로 사용합니다. 따라서 네 카운터는 가드레일이 적용된 모집단을 분할합니다. shadow → enforce 롤아웃 중 이 메트릭을 해석하는 방법은 관측 가능성을 참조하세요.

Prometheus 가드레일(--prometheus-guardrail-mode)이 활성화되면 같은 방식으로 결정을 기록하는 카운터 4개가 추가됩니다.

메트릭유형설명
mcp_prometheus_guardrail_admitted_total카운터활성화된 모든 검사를 통과한 쿼리
mcp_prometheus_guardrail_would_block_total카운터shadow 모드에서 검사에 실패했지만 계속 실행된 쿼리(레이블: reason)
mcp_prometheus_guardrail_blocked_total카운터enforce 모드에서 거부된 쿼리(레이블: reason)
mcp_prometheus_guardrail_fail_open_total카운터활성화된 평가를 사용할 수 없어 허용된 쿼리(레이블: reason)

reason은 would_block 및 blocked에서 selector, range, points 또는 cardinality이며, 해당 순서에서 처음 실패한 검사에 한 번만 집계됩니다. fail_open는 unparseable 또는 cardinality_unknown을 사용합니다. 선택적 카디널리티 정책은 캐시된 상위 N개 TSDB 통계를 사용해 카디널리티가 높은 것으로 알려진 메트릭에 명시적 범위를 요구합니다. 선택된 시계열을 추정하거나 누락된 메트릭이 안전함을 입증하지는 않습니다. 지원되지 않는 TSDB 엔드포인트에서는 이 정책이 허용 우선으로 동작합니다. backend 레이블은 없습니다.

라이브러리를 임베드하는 경우 GrafanaConfig.MeterProvider(GrafanaConfig.Logger에 대응하는 메트릭 설정)을 지정해야 합니다. 가드레일은 도구 핸들러 내부에서 실행되므로 생성자 옵션이 없으며, noop 전역 MeterProvider을 설치한 프로세스에서는 별도 설정이 없으면 모든 기록이 버려집니다.

느린 요청 로깅

--slow-request-threshold 플래그는 MCP 요청(도구 호출, 목록 조회, 리소스 읽기 등)이 지정된 시간을 초과할 때마다 구조화된 로그 이벤트를 출력합니다. 전체 디버그 로그를 지나치게 늘리지 않고 느린 쿼리와 도구 호출을 진단하는 데 유용합니다.

# Warn on any request slower than 500ms (works on all transports)
./mcp-grafana -t streamable-http --slow-request-threshold 500ms

# Same thing on stdio (the feature is transport-agnostic, unlike --metrics)
./mcp-grafana -t stdio --slow-request-threshold 500ms

# Log at INFO level instead of WARN (useful during investigation)
./mcp-grafana -t streamable-http --slow-request-threshold 500ms --slow-request-log-level info

로그 이벤트에는 다음 구조화된 속성이 포함됩니다.

속성설명
mcp.methodMCP 메서드(예: tools/call, tools/list, resources/read)
duration관측된 요청 소요 시간
threshold구성된 임계값
tool도구 이름(tools/call 메서드에만 포함)
error요청 실패 시 오류 값(최선의 노력으로 제공되는 컨텍스트이며, 내용은 상위 오류 래핑에 따라 결정됨)
error.type카디널리티가 제한된 오류 분류(유형이 지정되지 않은 오류의 경우 _OTHER)

느린 요청 로깅은 stdio를 포함한 모든 전송 방식에서 작동하며 --metrics이 필요하지 않습니다. 기본 임계값인 0는 로깅을 완전히 비활성화합니다. 프록시된 도구는 tools/call를 거치므로 자동으로 포함됩니다.

추적

분산 추적은 표준 OTEL_* 환경 변수를 통해 구성되며 --metrics 플래그와 독립적으로 작동합니다. OTEL_EXPORTER_OTLP_ENDPOINT(또는 신호별 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT)이 설정되면 서버는 OTLP/gRPC를 통해 추적을 내보냅니다.

# Send traces to a local Tempo instance
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 \
OTEL_EXPORTER_OTLP_INSECURE=true \
./mcp-grafana -t streamable-http

# Send traces to Grafana Cloud with authentication
OTEL_EXPORTER_OTLP_ENDPOINT=https://tempo-us-central1.grafana.net:443 \
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic ..." \
./mcp-grafana -t streamable-http

도구 호출 스팬은 의미 규칙에 따른 이름(tools/call <tool_name>)을 사용하며 gen_ai.tool.name, mcp.method.name, mcp.session.id 등의 속성을 포함합니다. 또한 서버는 도구 호출 요청의 _meta 필드에서 W3C 추적 컨텍스트 전파를 지원합니다.

로그

OTEL_EXPORTER_OTLP_ENDPOINT(또는 신호별 OTEL_EXPORTER_OTLP_LOGS_ENDPOINT)이 설정되면 서버는 기존 일반 텍스트 stderr 출력에 더해 OTLP/gRPC를 통해 구조화된 로그도 내보냅니다. otelslog 브리지는 활성 스팬의 trace_id 및 span_id를 자동으로 첨부하므로 로그 레코드를 서버가 이미 내보내는 추적과 연계할 수 있습니다. 트레이스와 로그는 각각 독립적으로 엔드포인트를 확인하므로 두 신호를 별도로 활성화할 수 있습니다. OTEL_EXPORTER_OTLP_TRACES_ENDPOINT만 설정하면 로그 내보내기 없이 트레이싱이 활성화되고, OTEL_EXPORTER_OTLP_LOGS_ENDPOINT만 설정하면 트레이싱 없이 로그 내보내기가 활성화되며, 일반 OTEL_EXPORTER_OTLP_ENDPOINT를 설정하면 둘 다 활성화됩니다.

일반 OTEL_EXPORTER_OTLP_ENDPOINT를 사용하지만 로그 내보내기를 비활성화하려는 경우(예: 백엔드가 LogsService를 지원하지 않는 경우) 다음을 설정하세요.

OTEL_LOGS_EXPORTER=none

이렇게 하면 엔드포인트 구성과 관계없이 서버가 OTLP 로그 내보내기를 생성하지 않으므로 unknown service opentelemetry.proto.collector.logs.v1.LogsService와 같은 오류를 방지할 수 있습니다.

OTLP 로깅이 활성화되어도 stderr 로깅은 변경되지 않습니다. 컨테이너 로그를 계속 사용하거나 원하는 경우 stderr를 /dev/null로 파이프할 수 있습니다.

# Send both logs and traces to a local OTel collector
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 \
OTEL_EXPORTER_OTLP_INSECURE=true \
./mcp-grafana -t streamable-http

전송 방식은 OTLP/gRPC입니다(기본 포트 4317). OTEL_EXPORTER_OTLP_LOGS_ENDPOINT(또는 일반 OTEL_EXPORTER_OTLP_ENDPOINT)을 원격 gRPC 엔드포인트로 지정하고 OTEL_EXPORTER_OTLP_LOGS_HEADERS(또는 OTEL_EXPORTER_OTLP_HEADERS)을 통해 인증 정보를 제공하면 Grafana Cloud와 같이 OTLP/gRPC를 허용하는 관리형 백엔드로 로그를 직접 보낼 수 있습니다. 위의 트레이싱 예시와 같은 방식입니다. 로컬 OTel collector는 선택 사항입니다. 팬아웃, 배치 처리 또는 여러 백엔드로의 라우팅에 유용하지만 필수는 아닙니다.

신호별 변형인 OTEL_EXPORTER_OTLP_LOGS_ENDPOINT, OTEL_EXPORTER_OTLP_LOGS_HEADERS, OTEL_EXPORTER_OTLP_LOGS_INSECURE, OTEL_EXPORTER_OTLP_LOGS_CERTIFICATE, OTEL_EXPORTER_OTLP_LOGS_TIMEOUT, OTEL_EXPORTER_OTLP_LOGS_COMPRESSION은 적용되며, 일반 OTEL_EXPORTER_OTLP_* 대응 항목보다 우선합니다. 전체 목록과 우선순위 규칙은 OTel exporter spec을 참조하세요.

구성된 collector에 연결할 수 없는 경우 로그 레코드는 메모리에 버퍼링됩니다(기본 큐: 2048). 큐가 가득 차면 가장 오래된 레코드가 삭제됩니다. 프로세스는 서비스를 차단하지 않고 계속 실행됩니다. 장애 중에도 손실 없는 버퍼링이 필요하다면 로컬 OTel collector를 구성하세요.

로그는 stdio 전송 방식에서도 내보내므로 IDE 클라이언트가 호출하는 로컬 mcp-grafana 인스턴스의 로그를 쉽게 중앙 집중화할 수 있습니다.

메트릭, 트레이싱, 로그를 사용하는 Docker 예시:

docker run --rm -p 8000:8000 \
  -e GRAFANA_URL=http://localhost:3000 \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your token> \
  -e OTEL_EXPORTER_OTLP_ENDPOINT=http://tempo:4317 \
  -e OTEL_EXPORTER_OTLP_INSECURE=true \
  grafana/mcp-grafana \
  -t streamable-http --metrics

Prometheus 쿼리 적용 정책

--prometheus-enforced-matchers을 사용하면 운영자가 모든 네이티브 Prometheus 쿼리에서 서버가 실행하는 각 벡터 선택기에 고정된 PromQL 레이블 매처 집합을 AND로 추가하여, 네이티브 Prometheus 도구가 읽을 수 있는 Prometheus 시계열을 제한할 수 있습니다. 데이터 소스에 노출해서는 안 되는 시계열(예: 민감한 테넌트 또는 고객 레이블이 포함된 메트릭)이 있지만 Prometheus 계층에서 액세스를 제한할 수 없는 경우 유용합니다.

# Only ever read prod/staging environments (allowlist)
./mcp-grafana --prometheus-enforced-matchers 'environment=~"prod|staging"' --disable-api --disable-rendering --disable-assistant

# Never read the vault or payments namespaces (exclusion)
./mcp-grafana --prometheus-enforced-matchers 'namespace!~"vault|payments"' --disable-api --disable-rendering --disable-assistant

작동 방식:

  • 매처는 시작 시 한 번 파싱되며(잘못된 입력이 있으면 서버 시작이 중단됨), 각 쿼리의 모든 벡터 선택기에 추가됩니다. 사용자 쿼리는 적용된 범위 안에서 결과를 좁히기만 할 수 있으며, 범위를 넓힐 수는 없습니다.
  • query_prometheus, query_prometheus_histogram, run_panel_query의 Prometheus 패널에 적용됩니다.
  • list_prometheus_label_names, list_prometheus_label_values, list_prometheus_metric_names을 통한 네이티브 Prometheus 검색에도 매처가 적용됩니다. 선택기가 제공되지 않은 경우에도 모든 시계열 선택기에 적용됩니다.
  • 적용 정책이 활성화된 동안에는 list_prometheus_metric_metadata이 거부됩니다. Prometheus 메타데이터 엔드포인트는 시계열 레이블로 필터링할 수 없으며 여러 대상의 메타데이터를 병합합니다. Cloud Monitoring 검색 API도 전체 Prometheus 매처 정책을 적용할 수 없으므로 거부됩니다.
  • Fail closed 방식으로 동작합니다. 파싱할 수 없는 쿼리는 필터링 없이 전송하는 대신 거부됩니다.

[!IMPORTANT] 활성화된 다른 도구는 이 매처를 우회할 수 있습니다. grafana_api_request을 --disable-api로, 렌더링 도구를 --disable-rendering으로, Grafana Assistant를 --disable-assistant(또는 --disable-write)으로 비활성화하세요. 특히 render_grafana_app은 query_datasource 소스를 통해 필터링되지 않은 Prometheus 쿼리를 보낼 수 있습니다. --disable-dsquery는 해당 소스를 닫지만 서버 측 패널 렌더링은 비활성화하지 않습니다. 기존 대시보드 스냅샷에도 제한되지 않은 데이터가 포함될 수 있습니다. 이 점이 중요하다면 --disable-snapshot을 사용하세요.

Loki 쿼리 적용 정책

--loki-enforced-matchers을 사용하면 운영자가 모든 네이티브 Loki 쿼리에서 서버가 실행하는 각 쿼리에 고정된 LogQL 레이블 매처 집합을 AND로 추가하여, 서버가 읽을 수 있는 Loki 로그 스트림을 제한할 수 있습니다. 데이터 소스에 노출해서는 안 되는 스트림(예: 민감한 정보가 포함될 수 있는 로그)이 있지만 Grafana 또는 Loki 계층에서 액세스를 제한할 수 없는 경우 유용합니다(OSS에는 데이터 소스별 또는 사용자별 레이블 액세스 제어가 없습니다).

# Only ever read prod/staging environments (allowlist)
./mcp-grafana --loki-enforced-matchers 'environment=~"prod|staging"' --disable-api

# Never read the vault or payments namespaces (exclusion)
./mcp-grafana --loki-enforced-matchers 'namespace!~"vault|payments"' --disable-api

작동 방식:

  • 매처는 시작 시 한 번 파싱되며(잘못된 입력이 있으면 서버 시작이 중단됨), 각 쿼리의 모든 스트림 선택기에 추가됩니다. Loki는 선택기 내 매처를 AND로 결합하므로 사용자 쿼리는 적용된 범위 안에서 결과를 좁히기만 할 수 있으며, 범위를 넓힐 수는 없습니다. 정책과 충돌하는 사용자 선택기(예: 제외 정책에서 {namespace="vault"}을 요청하는 경우)는 결과를 반환하지 않습니다.
  • query_loki_logs, query_loki_stats, query_loki_patterns, list_loki_label_names, list_loki_label_values에 적용됩니다.
  • Fail closed 방식으로 동작합니다. 파싱할 수 없는 쿼리는 필터링 없이 전송하는 대신 거부됩니다.
  • VictoriaLogs 데이터 소스는 안전하게 재작성할 수 없는 LogsQL을 사용하므로 적용 정책이 활성화된 동안 완전히 거부됩니다.
  • 순수 부정 매처는 레이블 열거 엔드포인트의 범위를 제한할 수 없습니다(Loki는 긍정 매처가 없는 단독 선택기를 거부함). --loki-label-enumeration-fallback로 이 예외 상황을 제어하세요(기본값은 reject, 또는 레이블 메타데이터의 범위 없는 열거를 허용하려면 unfiltered을 사용하세요. 로그 줄은 노출되지 않습니다). 긍정/허용 목록 매처에는 영향을 주지 않습니다.

[!IMPORTANT] 적용 정책은 Loki 쿼리 도구에만 적용됩니다. 다른 도구는 적용된 백엔드를 거치지 않는 경로로 Loki 로그 데이터에 접근할 수 있으므로, 제한을 실제로 적용하려면 다음 도구도 비활성화해야 합니다.

  • --disable-api — grafana_api_request은 Loki 데이터 소스 프록시에 직접 쿼리를 보낼 수 있습니다(완전한 우회).
  • --disable-rendering — get_panel_image은 Loki 패널을 서버 측에서 렌더링하여 제한되지 않은 로그 줄이 포함된 이미지를 생성합니다.
  • --disable-assistant — ask_assistant는 모든 스트림을 서버 측에서 읽는 Grafana Assistant에 위임합니다. 쓰기 도구가 활성화된 경우에만 등록되므로 --disable-write으로도 비활성화할 수 있습니다.

서버는 시작 시 아직 활성화된 각 도구의 이름을 포함한 경고를 기록합니다. run_panel_query는 안전합니다(적용된 쿼리 경로를 재사용함). Tempo 도구는 Loki 로그가 아닌 트레이스를 쿼리하므로 우회 경로가 아닙니다. 대시보드 스냅샷(--disable-snapshot)에도 적용 정책 외부에서 캡처한 로그 패널 데이터가 포함될 수 있습니다.

문제 해결

Grafana 버전 호환성

데이터 소스 관련 도구를 사용할 때 다음 오류가 발생하면:

get datasource by uid : [GET /datasources/uid/{uid}][400] getDataSourceByUidBadRequest {"message":"id is invalid"}

일반적으로 Grafana 9.0 이전 버전을 사용하고 있다는 뜻입니다. /datasources/uid/{uid} API 엔드포인트는 Grafana 9.0에서 도입되었으며, 이전 버전에서는 데이터 소스 작업이 실패합니다.

해결 방법: 이 문제를 해결하려면 Grafana 인스턴스를 9.0 이상으로 업그레이드하세요.

개발

기여를 환영합니다! 먼저 CONTRIBUTING.md를 읽어 주세요. 이 문서에서는 이 서버에 포함할 내용과 제안 방법을 설명합니다.

새 도구를 추가하는 경우 코드를 작성하기 전에 도구 제안서를 제출해 주세요. 기본적으로 활성화되는 모든 도구는 모든 사용자의 모든 요청에서 모델에 전달되므로, 완성된 풀 리퀘스트를 거절하기보다는 아이디어를 먼저 논의하고자 합니다. 버그 수정, 문서, 테스트, 기존 도구의 새 매개변수에는 제안서가 필요하지 않습니다. 바로 PR을 보내 주세요.

이 프로젝트는 Go로 작성되었습니다. 도구 버전과 개발 작업은 mise.toml에 있습니다. mise를 설치하고, 고정된 도구를 가져오려면 mise install을 실행한 다음, 작업 목록을 보려면 mise tasks를 실행하세요.

서버를 로컬에서 STDIO 모드로 실행하려면(로컬 개발의 기본 모드) 다음을 사용하세요.

mise run run

서버를 로컬에서 SSE 모드로 실행하려면 다음을 사용하세요.

go run ./cmd/mcp-grafana --transport sse

사용자 지정 빌드 Docker 이미지에서 SSE 전송을 사용해 서버를 실행할 수도 있습니다. 게시된 Docker 이미지와 마찬가지로 이 사용자 지정 이미지의 엔트리포인트도 기본적으로 SSE 모드로 실행됩니다. 이미지를 빌드하려면 다음을 사용하세요.

mise run build-image

이미지를 SSE 모드(기본값)로 실행하려면 다음을 사용하세요.

docker run -it --rm -p 8000:8000 mcp-grafana:latest

대신 STDIO 모드로 실행해야 한다면 전송 설정을 재정의하세요.

docker run -it --rm mcp-grafana:latest -t stdio

테스트

사용할 수 있는 테스트는 세 가지 유형입니다.

  1. 단위 테스트(외부 종속성 필요 없음):
mise run test-unit

다음 명령으로도 단위 테스트를 실행할 수 있습니다.

mise run test
  1. 통합 테스트(Docker 컨테이너가 실행 중이어야 함):
mise run test-integration
  1. 클라우드 테스트(클라우드 Grafana 인스턴스와 인증 정보 필요):
mise run test-cloud

참고: 클라우드 테스트는 CI에서 자동으로 구성됩니다. 로컬 개발 환경에서는 자체 Grafana Cloud 인스턴스와 인증 정보를 설정해야 합니다.

보다 포괄적인 통합 테스트를 실행하려면 Grafana 인스턴스가 로컬 포트 3000에서 실행 중이어야 합니다. Docker Compose로 시작할 수 있습니다.

docker-compose up -d

도구를 추가하는 경우 해당 도구의 통합 테스트도 추가해 주세요. 기존 테스트를 좋은 출발점으로 삼을 수 있습니다.

린트

코드 린트를 실행하려면 다음을 사용하세요.

mise run lint

여기에는 jsonschema 구조체 태그의 이스케이프되지 않은 쉼표를 검사하는 사용자 지정 린터가 포함됩니다. description 필드의 쉼표는 조용한 잘림을 방지하기 위해 \\,로 이스케이프해야 합니다. 이 린터만 실행하려면 다음을 사용하세요.

mise run lint-jsonschema

자세한 내용은 JSONSchema Linter 문서를 참조하세요.

라이선스

이 프로젝트는 Apache License, Version 2.0에 따라 라이선스가 부여됩니다.