클라이언트 구성 예시

클라이언트 구성 예시 (Client configuration examples)

이 페이지는 자격 증명, 설치 옵션, 그리고 일반적인 편집기와 런타임에 대한 MCP 클라이언트 JSON 패턴을 안내해요. MCP 서버는 로컬 Grafana와 Grafana Cloud에서 모두 동작해요. Grafana Cloud에서는 아래 예시의 http://localhost:3000 대신 인스턴스 URL(예: https://myinstance.grafana.net)을 사용해요.

출처: 문서

본문

달성할 내용

uvx, 바이너리, Docker, VS Code 원격, 디버그 모드, TLS에 대한 동작하는 구성 블록을 복사할 수 있어요.

시작하기 전에

1. 서비스 계정 토큰을 사용한다면, Grafana에서 도구에 필요한 권한으로 서비스 계정을 만들고 토큰을 생성한 뒤 구성에 복사해 넣어요. Grafana 서비스 계정 문서를 참고해요. 팁: 모든 범위를 세밀하게 조정하고 싶지 않다면 기본 제공되는 Editor 역할을 할당하는 것이 간단한 방법이에요. 다만 최소 권한보다는 넓은 권한이에요.

참고 환경 변수 GRAFANA_API_KEY는 GRAFANA_SERVICE_ACCOUNT_TOKEN으로 대체되었어요. 이전 이름도 여전히 동작하지만 경고를 기록할 수 있어요.

2. 설정 (Set up)의 방법 중 하나로 mcp-grafana를 설치해요.
3. 아래 패턴 중 하나로 클라이언트 구성에 서버 블록을 추가해요.

조직 대상 지정과 사용자 지정 헤더는 다중 조직 및 헤더 (Multi-organization and headers)를 참고해요.

다중 조직 지원

다음 중 하나로 상호작용할 조직을 지정할 수 있어요:

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

조직 ID가 제공되면 MCP 서버는 Grafana로 가는 모든 요청에 X-Grafana-Org-Id 헤더를 설정해, 지정된 조직 컨텍스트 안에서 작업이 수행되도록 해요.

조직 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\"}"
      }
    }
  }
}

설치 옵션

mcp-grafana는 여러 방식으로 설치할 수 있어요:

• uvx (권장): uv가 설치되어 있다면 추가 설정이 필요 없어요 — uvx가 서버를 자동으로 다운로드하고 실행해요:

uvx mcp-grafana

• Docker 이미지: Docker Hub의 미리 빌드된 Docker 이미지를 사용해요.중요: Docker 이미지의 엔트리포인트는 기본적으로 SSE 모드로 MCP 서버를 실행하도록 구성되어 있지만, 대부분의 사용자는 Claude Desktop 같은 AI 어시스턴트와 직접 통합하기 위해 STDIO 모드를 사용하고 싶어할 거예요:STDIO 모드: stdio 모드에서는 -t stdio로 기본값을 명시적으로 덮어써야 하고, stdin을 열어두려면 -i 플래그를 포함해야 해요:

docker pull grafana/mcp-grafana
# 로컬 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
# 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 모드: 이 모드에서는 서버가 클라이언트가 연결하는 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> grafana/mcp-grafana

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> 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> \
  grafana/mcp-grafana \
  -t streamable-http \
  --address :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/cmd/mcp-grafana@latest

• Helm으로 Kubernetes에 배포: grafana-community helm-charts 저장소의 Helm 차트를 사용해요.

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

클라이언트에 서버 추가

클라이언트 구성 파일에 서버 구성을 추가해요. 예를 들어 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 모드를 덮어쓰기 때문에 여기서 필수예요. VSCode와 원격 MCP 서버 사용하기 VSCode를 사용하면서 MCP 서버를 SSE 모드(전송을 덮어쓰지 않고 Docker 이미지를 사용할 때의 기본값)로 실행하고 있다면 .vscode/settings.json에 다음이 포함되어 있어야 해요:

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

SSE 서버 앞에서 TLS를 종료한다면(또는 리스너가 여전히 /sse에서 SSE를 말한다면), 클라이언트 URL은 type: "sse"와 함께 https://localhost:8443/sse처럼 보일 수 있어요. streamable-http를 서버 TLS로 실행한다면(예: -t streamable-http, --address :8443, --server.tls-*를 사용하는 Docker 예시), MCP HTTP 엔드포인트는 --endpoint-path(기본값 /mcp)이므로 예를 들어 https://localhost:8443/mcp가 돼요. 이것은 /sse와 같지 않아요. streamable HTTP에는 편집기 문서가 안내하는 클라이언트와 type을 사용하고, 위 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>"
      }
    }
  }
}

참고 표준 구성과 마찬가지로 -t stdio 인자는 Docker 이미지의 기본 SSE 모드를 덮어쓰는 데 필요해요.

TLS 구성 (클라이언트에서 Grafana로)

Grafana 인스턴스가 mTLS 뒤에 있거나 사용자 지정 TLS 인증서를 요구한다면, Grafana를 호출할 때 올바른 인증서를 사용하도록 MCP 서버를 구성해요:

• --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 데이터소스 클라이언트
• Incident 관리 클라이언트
• Sift 조사 클라이언트
• 경보(alerting) 클라이언트
• Asserts 클라이언트

직접 CLI 사용 예시: 자체 서명(self-signed) 인증서로 테스트하려면:

./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

프로그래밍 방식 사용 (Go): 이 라이브러리를 프로그래밍 방식으로 사용한다면 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)

간단한 개요는 클라이언트 TLS (Grafana 연결)를 참고해요.

서버 TLS 구성 (Streamable HTTP 전송 전용)

streamable HTTP 전송(-t streamable-http)을 사용할 때 MCP 서버가 HTTP 대신 HTTPS를 제공하도록 구성할 수 있어요. 이는 MCP 클라이언트와 서버 자체 사이의 연결을 보호해야 할 때 유용해요. 서버는 streamable HTTP 전송에 대해 다음 TLS 구성 옵션을 지원해요:

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

참고: 이 플래그들은 위에서 문서화한 클라이언트 TLS 플래그와 완전히 별개예요. 클라이언트 TLS 플래그는 MCP 서버가 Grafana에 연결하는 방식을 구성하고, 서버 TLS 플래그는 streamable HTTP 전송을 사용할 때 클라이언트가 MCP 서버에 연결하는 방식을 구성해요. 예시: HTTPS streamable HTTP 서버 예시:

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

그러면 MCP 서버가 HTTPS 포트 8443에서 시작돼요. 클라이언트는 http://localhost:8000/mcp 대신 https://localhost:8443/mcp에 연결해요(기본 --endpoint-path는 /mcp). Docker 예시: 서버 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 \
  --address :8443 \
  --server.tls-cert-file /certs/server.crt \
  --server.tls-key-file /certs/server.key

더 자세한 내용은 서버 TLS (streamable-http)를 참고해요.

다음 단계

• 헬스 체크 엔드포인트 (Health check endpoint)
• 관측 가능성 (메트릭 및 트레이싱) (Observability - metrics and tracing)
• 문제 해결 (Troubleshooting)