# https://github.com/grafana/mcp-grafana 项目说明书

生成时间：2026-06-02 08:39:35 UTC

## 目录

- [项目概述](#overview)
- [快速开始](#quickstart)
- [安装与配置](#installation)
- [认证与授权](#authentication)
- [部署与运维](#deployment)
- [仪表板工具](#dashboard-tools)
- [数据源工具](#datasource-tools)
- [查询执行工具](#query-tools)
- [告警管理工具](#alerting-tools)
- [故障排除与常见问题](#troubleshooting)

<a id='overview'></a>

## 项目概述

### 相关页面

相关主题：[快速开始](#quickstart), [认证与授权](#authentication)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [internal/linter/jsonschema/README.md](https://github.com/grafana/mcp-grafana/blob/main/internal/linter/jsonschema/README.md)
- [internal/linter/openapi/testdata/src/github.com/grafana/grafana-openapi-client-go/client/datasources/fake.go](https://github.com/grafana/mcp-grafana/blob/main/internal/linter/openapi/testdata/src/github.com/grafana/grafana-openapi-client-go/client/datasources/fake.go)
- [internal/linter/openapi/testdata/src/testpkg/usage.go](https://github.com/grafana/mcp-grafana/blob/main/internal/linter/openapi/testdata/src/testpkg/usage.go)
- [internal/linter/openapi/testdata/src/testpkg/usage_test.go](https://github.com/grafana/mcp-grafana/blob/main/internal/linter/openapi/testdata/src/testpkg/usage_test.go)
- [mcpgrafana.go](https://github.com/grafana/mcp-grafana/blob/main/mcpgrafana.go)
- [server.json](https://github.com/grafana/mcp-grafana/blob/main/server.json)
</details>

# 项目概述

## 简介

mcp-grafana 是一个 Grafana Model Context Protocol (MCP) 服务器实现，旨在为 AI 模型（如 Claude、GPT 等大型语言模型）提供与 Grafana 可视化平台交互的能力。通过 MCP 协议，该项目使 AI 助手能够安全地查询和操作 Grafana 中的各类资源，包括仪表板、面板、日志数据、告警规则等。

该项目由 Grafana 官方维护，采用 Go 语言开发，支持通过多种传输模式（MCP stdio、HTTP/SSE、streamable-http）运行，并提供了丰富的 Grafana 数据源查询能力。

## 核心功能

### 工具集（Tools）

mcp-grafana 提供了多个 MCP 工具，涵盖以下功能领域：

| 功能领域 | 主要工具 | 说明 |
|---------|---------|------|
| 仪表板 | `get_dashboard`、`list_dashboards`、`update_dashboard` | 仪表板的查询和更新 |
| 面板 | `get_panel_image`、`get_dashboard_panel_queries` | 面板渲染和查询提取 |
| 数据源 | `query_prometheus_logs`、`query_loki_logs`、`query_influxd`、`query_graphite` | 多数据源查询 |
| 告警 | `alerting_list_rules`、`alerting_manage_rules`、`alerting_manage_routing` | 告警规则管理 |
| 短链接 | `generate_deeplink` | 生成 Grafana 短 URL |
| 插件 | `get_plugin_info` | 插件信息查询 |
| API | `request` | 通用 HTTP API 请求 |

资料来源：[server.json](https://github.com/grafana/mcp-grafana/blob/main/server.json)

### 数据源支持

截至 v0.15.0 版本，项目支持以下数据源类型：

- **Prometheus/Loki**：日志和指标查询
- **VictoriaMetrics**：PromQL 查询支持
- **OpenSearch**：日志和搜索查询
- **InfluxDB**：支持 Flux 和 InfluxQL 查询语言
- **Graphite**：指标查询和函数发现
- **Pyroscope**：性能分析数据查询
- **Cloud Monitoring**：GCP 项目监控
- **Snowflake**：云数据仓库查询
- **Amazon Athena**：AWS 大数据分析

资料来源：[v0.15.0 发布说明](https://github.com/grafana/mcp-grafana/releases/tag/v0.15.0)

### 认证机制

当前支持的认证方式包括：

1. **服务账号令牌 (Service Account Tokens)**：通过 `GRAFANA_AUTH` 环境变量配置
2. **基础认证 (Basic Auth)**：用户名/密码组合
3. **请求头转发**：在 SSE 和 streamable-http 模式下支持 Cookie、Authorization 等请求头转发

```go
// 认证配置示例
type GrafanaConfig struct {
    URL    string
    Auth   string  // Base64 encoded credentials or token
}
```

资料来源：[v0.11.5 发布说明](https://github.com/grafana/mcp-grafana/releases/tag/v0.11.5)

## 架构设计

### 传输层架构

mcp-grafana 支持多种 MCP 协议传输模式，适用于不同部署场景：

```mermaid
graph TD
    A[MCP Client] -->|stdio| B[Stdio Transport]
    A -->|HTTP| C[SSE Transport]
    A -->|HTTP| D[Streamable HTTP Transport]
    
    B --> E[Grafana MCP Server]
    C --> E
    D --> E
    
    E --> F[HTTP Client]
    F --> G[Grafana API]
    
    E --> H[RoundTrippers]
    H -->|上下文传播| F
    H -->|认证头| F
    H -->|日志记录| F
```

### 代码质量检查系统

项目内置了两套代码检查工具，确保 MCP 工具定义的准确性：

#### JSONSchema Linter

用于检测和修复 Go 结构体标签中 `jsonschema` 描述字段的逗号转义问题。

```go
// 问题代码（逗号会被截断）
Field string `jsonschema:"description=This is a description, but it will be truncated here"`

// 正确写法（需要使用 \\, 转义）
Field string `jsonschema:"description=This is a description\\, and it will be fully included"`
```

运行检查命令：
```shell
make lint-jsonschema
```

自动修复命令：
```shell
make lint-jsonschema-fix
```

资料来源：[internal/linter/jsonschema/README.md](https://github.com/grafana/mcp-grafana/blob/main/internal/linter/jsonschema/README.md)

#### OpenAPI Linter

验证 OpenAPI 客户端调用的正确性，确保使用上下文感知的参数对象：

```go
// 错误用法 - 丢失请求上下文
c.GetDataSources()
c.GetDataSourceByUID("myuid")

// 正确用法 - 使用 WithParams 变体
c.GetDataSourcesWithParams(nil)
c.GetDataSourceByUIDWithParams(nil)
```

测试文件中的调用不会触发此检查：
```go
func testHelper(c datasources.ClientService) {
    // 测试文件中的调用不会被标记
    c.GetDataSources()
    c.GetDataSourceByUID("myuid")
}
```

资料来源：[internal/linter/openapi/testdata/src/testpkg/usage.go](https://github.com/grafana/mcp-grafana/blob/main/internal/linter/openapi/testdata/src/testpkg/usage.go)

## 社区关注的问题

### 高优先级功能请求

| Issue | 类型 | 说明 |
|-------|------|------|
| #284 | 认证 | OAuth/SSO 认证支持（Okta、Google、Azure AD） |
| #151 | 使用方式 | 普通用户的工作流程优化 |
| #820 | 功能 | 创建短 URL 工具（/goto/&lt;uid&gt;） |
| #883 | 功能 | `get_panel_image` 支持 `orgId` 参数 |
| #761 | 功能 | `query_loki_logs` 结果分页/分块 |

### 已知限制

1. **多组织支持**：虽然 Grafana MCP 支持跨组织操作，但 `get_panel_image` 工具尚未暴露 `orgId` 参数
2. **日志量控制**：Loki 日志查询返回大量结果时可能超出 LLM 输出处理预算
3. **短链接生成**：`generate_deeplink` 生成的 Explore URL 包含完整 JSON，URL 较长

## 版本历史

| 版本 | 主要新增功能 |
|------|-------------|
| v0.15.0 | Snowflake 数据源、Amazon Athena 支持 |
| v0.14.0 | 通用 API 请求工具、OpenSearch 数据源、插件信息查询 |
| v0.13.1 | VictoriaMetrics PromQL 支持、告警规则录制规则包含 |
| v0.12.0 | InfluxDB、Graphite 数据源支持 |
| v0.11.4 | Pyroscope 查询、通用 Kubernetes API 客户端 |
| v0.11.3 | 告警路由管理工具、面板过滤和模板变量 |

## 快速开始

### 环境要求

- Go 1.21+
- Grafana 9.x 或更高版本
- 有效的 Grafana 服务账号或 API 密钥

### 配置方式

```bash
# 通过环境变量配置
export GRAFANA_URL=https://your-grafana.example.com
export GRAFANA_AUTH=your-service-account-token

# 运行 MCP 服务器
go run ./cmd/mcp-grafana
```

### 传输模式选择

```mermaid
graph LR
    A[使用场景] --> B{交互式工具}
    A --> C{远程服务}
    A --> D{生产部署}
    
    B --> E[Stdio 模式]
    C --> F[SSE 模式]
    D --> G[Streamable HTTP 模式]
```

- **Stdio**：适用于本地 CLI 工具集成
- **SSE**：适用于需要服务端推送的场景
- **Streamable HTTP**：适用于现代微服务架构

## 相关资源

- [官方文档](https://grafana.com/docs/mcp-grafana/)
- [问题追踪](https://github.com/grafana/mcp-grafana/issues)
- [发布页面](https://github.com/grafana/mcp-grafana/releases)
- [Docker Hub](https://hub.docker.com/r/mcp/grafana)

---

<a id='quickstart'></a>

## 快速开始

### 相关页面

相关主题：[安装与配置](#installation), [部署与运维](#deployment)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docs/sources/set-up/install-with-uvx.md](https://github.com/grafana/mcp-grafana/blob/main/docs/sources/set-up/install-with-uvx.md)
- [docs/sources/set-up/install-with-docker.md](https://github.com/grafana/mcp-grafana/blob/main/docs/sources/set-up/install-with-docker.md)
- [docs/sources/set-up/deploy-with-helm.md](https://github.com/grafana/mcp-grafana/blob/main/docs/sources/set-up/deploy-with-helm.md)
- [docker-compose.yaml](https://github.com/grafana/mcp-grafana/blob/main/docker-compose.yaml)
</details>

# 快速开始

本文档为 Grafana MCP (Model Context Protocol) 服务器提供快速入门指南，帮助用户在多种环境中快速部署和配置该服务。Grafana MCP 是一个将 Grafana 与大型语言模型 (LLM) 集成的中间件服务，允许 AI 助手通过标准化的 MCP 协议与 Grafana 进行交互，从而实现仪表板查询、告警管理、数据源操作等功能。

## 环境要求

在开始安装之前，请确保满足以下基本要求：

| 要求项 | 说明 |
|--------|------|
| Go 版本 | 1.23 或更高版本（用于本地编译） |
| Docker | 20.10+ (如使用容器部署) |
| Helm | 3.0+ (如使用 Kubernetes 部署) |
| Grafana 版本 | 10.0+ |
| 网络访问 | 能访问目标 Grafana 实例的 API 端点 |

## 安装方式概览

Grafana MCP 支持三种主要的安装和部署方式，适用于不同的使用场景：

```mermaid
graph TD
    A[Grafana MCP 安装方式] --> B[uvx 本地安装]
    A --> C[Docker 容器部署]
    A --> D[Helm Kubernetes 部署]
    
    B --> B1[适合开发者测试]
    B --> B2[单用户本地环境]
    
    C --> C1[适合服务器部署]
    C --> C2[支持多种 MCP 客户端]
    
    D --> D1[适合生产环境]
    D --> D2[支持高可用和扩展]
```

## 使用 uvx 本地安装

`uvx` 是 uv 包管理器的命令执行工具，可快速启动 Grafana MCP 服务而无需手动编译。

### 前置条件

确保已安装 uv 包管理器。如未安装，可通过以下命令安装：

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

### 启动服务

使用 `uvx` 直接启动 Grafana MCP 服务：

```bash
uvx mcp-grafana
```

服务启动后将自动监听标准 MCP 端口，客户端可立即连接。

### 配置文件

默认情况下，服务使用环境变量进行配置。关键配置项包括：

| 环境变量 | 说明 | 示例 |
|----------|------|------|
| `GRAFANA_AUTH` | 认证凭据（服务账户令牌或 Basic Auth） | `Bearer eyJrIjoi...` |
| `GRAFANA_URL` | Grafana 实例地址 | `https://grafana.example.com` |
| `ALLOWED_HOSTS` | 允许访问的主机列表（逗号分隔） | `localhost,127.0.0.1` |

完整的环境变量列表请参考配置文档。

## 使用 Docker 部署

Docker 部署方式适合需要在服务器上长期运行、或需要与多个 MCP 客户端集成的场景。

### 基础运行

使用 Docker 运行 Grafana MCP 服务的最简方式：

```bash
docker run -p 8080:8080 \
  -e GRAFANA_URL=https://your-grafana.com \
  -e GRAFANA_AUTH=Bearer YOUR_TOKEN \
  mcp/grafana
```

### 使用 Docker Compose

项目提供了 `docker-compose.yaml` 配置文件，便于快速启动完整测试环境：

```bash
docker-compose up -d
```

Docker Compose 配置通常包含 Grafana MCP 服务以及可选的 Grafana 开发实例，便于即开即用的测试体验。

### Docker 镜像配置

| 参数 | 说明 |
|------|------|
| `-p 8080:8080` | 映射 MCP 服务端口 |
| `-e GRAFANA_URL` | Grafana API 地址 |
| `-e GRAFANA_AUTH` | 服务账户令牌 |
| `-v` | 可选：挂载配置文件或证书 |

## 使用 Helm 部署到 Kubernetes

对于生产环境，推荐使用 Helm chart 将 Grafana MCP 部署到 Kubernetes 集群。

### 添加 Helm 仓库

首先添加 Grafana 官方 Helm 仓库：

```bash
helm repo add grafana https://grafana.github.io/helm-charts
helm repo update
```

### 安装 Chart

使用默认配置安装：

```bash
helm install mcp-grafana grafana/mcp-grafana
```

### 自定义配置

通过 `values.yaml` 文件或命令行参数自定义部署：

```bash
helm install mcp-grafana grafana/mcp-grafana \
  --set grafana.url=https://grafana.example.com \
  --set grafana.auth=Bearer YOUR_TOKEN \
  --set service.type=LoadBalancer
```

### 关键配置参数

| 参数路径 | 说明 | 默认值 |
|----------|------|--------|
| `grafana.url` | Grafana 实例地址 | - |
| `grafana.auth` | 认证凭据 | - |
| `service.type` | Kubernetes Service 类型 | ClusterIP |
| `replicaCount` | 副本数量 | 1 |
| `resources.limits.cpu` | CPU 限制 | 500m |
| `resources.limits.memory` | 内存限制 | 512Mi |

## 认证配置

Grafana MCP 支持多种认证方式。根据社区反馈（Issue #284），当前版本主要支持：

| 认证方式 | 说明 | 适用场景 |
|----------|------|----------|
| 服务账户令牌 | 使用 Grafana 服务账户生成的令牌 | 推荐用于生产环境 |
| Basic Auth | 用户名/密码组合 | 仅适用于未禁用 Basic Auth 的实例 |

> **注意**：社区请求支持 OAuth/SSO 认证（Okta、Google OAuth、Azure AD 等），这是目前高优先级的功能需求。如有相关需求，请关注 Issue #284。

### 生成服务账户令牌

1. 登录 Grafana Web UI
2. 进入 **Configuration → Service Accounts**
3. 创建新服务账户并生成令牌
4. 确保分配所需的最小权限（Viewer、Editor 或 Admin 根据工具使用需求）

## 验证安装

安装完成后，可通过以下方式验证服务是否正常运行：

1. **健康检查端点**：访问服务的健康检查端点确认服务响应
2. **MCP 客户端连接**：使用 MCP 兼容客户端（如 Claude Desktop、Cline 等）连接服务
3. **列出可用工具**：成功连接后应能看到所有可用的 MCP 工具

```mermaid
graph LR
    A[MCP 客户端] -->|连接| B[Grafana MCP 服务]
    B -->|认证请求| C[Grafana API]
    C -->|数据响应| B
    B -->|工具列表| A
    
    D[可用工具] --> E[query_variable_values]
    D --> F[get_dashboard]
    D --> G[run_query]
    D --> H[alerting_manage_rules]
```

## 常见问题

### 服务无法连接到 Grafana

- 检查网络连通性，确保能访问 Grafana API
- 验证 `GRAFANA_URL` 配置正确（包含协议前缀）
- 确认服务账户令牌有效且未过期

### MCP 客户端连接失败

- 检查防火墙设置，确保 8080 端口可访问
- 确认 `ALLOWED_HOSTS` 包含客户端所在主机
- 查看服务日志排查具体错误原因

### Docker 容器启动失败

- 确认 Docker 版本满足要求（20.10+）
- 检查环境变量配置是否正确
- 使用 `docker logs <container_id>` 查看详细错误信息

## 下一步

完成快速开始后，建议进一步了解：

- **工具使用**：查看各 MCP 工具的详细用法
- **配置参考**：完整的配置选项和高级设置
- **数据源支持**：已支持的数据源类型和查询方式
- **故障排除**：常见问题排查指南

## 相关资源

- 官方文档：[https://grafana.com/docs/mcp-grafana](https://grafana.com/docs/mcp-grafana)
- GitHub 问题反馈：[Issue #151](https://github.com/grafana/mcp-grafana/issues/151) - 普通用户工作流程讨论
- 最新版本发布说明：查看 [Releases](https://github.com/grafana/mcp-grafana/releases) 页面

---

<a id='installation'></a>

## 安装与配置

### 相关页面

相关主题：[认证与授权](#authentication), [部署与运维](#deployment)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [cmd/mcp-grafana/main.go](https://github.com/grafana/mcp-grafana/blob/main/cmd/mcp-grafana/main.go)
- [docs/sources/configure/command-line-flags.md](https://github.com/grafana/mcp-grafana/blob/main/docs/sources/configure/command-line-flags.md)
- [docs/sources/configure/transports-and-addresses.md](https://github.com/grafana/mcp-grafana/blob/main/docs/sources/configure/transports-and-addresses.md)
- [docs/sources/set-up/client-configuration-examples.md](https://github.com/grafana/mcp-grafana/blob/main/docs/sources/set-up/client-configuration-examples.md)
- [docs/sources/set-up/installation.md](https://github.com/grafana/mcp-grafana/blob/main/docs/sources/set-up/installation.md)
</details>

# 安装与配置

本文档详细介绍 Grafana MCP Server 的安装方式、环境配置、认证机制以及传输协议设置。

## 概述

Grafana MCP Server 是一个基于 Model Context Protocol (MCP) 的服务器实现，允许 AI 助手与 Grafana 进行交互。通过该服务器，用户可以查询监控数据、管理仪表板、操作告警规则等。

## 部署方式

### Docker 部署

推荐使用 Docker 容器方式部署 Grafana MCP Server：

```bash
docker run -p 8080:8080 \
  -e GRAFANA_URL=http://localhost:3000 \
  -e GRAFANA_TOKEN=your-service-account-token \
  mcp/grafana
```

当前 Docker 镜像仅提供 `latest` 标签，尚不支持版本化标签。相关社区讨论可参见 [Issue #180](https://github.com/grafana/mcp-grafana/issues/180)。

### 二进制安装

从 [GitHub Releases](https://github.com/grafana/mcp-grafana/releases) 页面下载对应平台的二进制文件：

```bash
# Linux AMD64
curl -L -o mcp-grafana https://github.com/grafana/mcp-grafana/releases/latest/download/mcp-grafana-linux-amd64
chmod +x mcp-grafana
sudo mv mcp-grafana /usr/local/bin/
```

## 环境变量配置

Grafana MCP Server 支持通过环境变量进行配置。以下是主要配置项：

| 环境变量 | 描述 | 必需 | 默认值 |
|---------|------|------|--------|
| `GRAFANA_URL` | Grafana 实例的 URL 地址 | 是 | - |
| `GRAFANA_TOKEN` | Grafana 服务账户令牌 | 是* | - |
| `GRAFANA_AUTH` | Basic 认证用户:密码 | 是* | - |
| `LOG_LEVEL` | 日志级别 | 否 | `info` |
| `LOG_FORMAT` | 日志格式 (`json`/`text`) | 否 | `text` |

> **注意**：`GRAFANA_TOKEN` 和 `GRAFANA_AUTH` 至少需要配置其中之一。

## 命令行参数

Grafana MCP Server 提供丰富的命令行参数用于配置：

```bash
mcp-grafana [选项]
```

### 通用选项

| 参数 | 描述 | 默认值 |
|------|------|--------|
| `--config <path>` | 配置文件路径 | - |
| `--host <address>` | 监听地址 | `127.0.0.1` |
| `--port <number>` | 监听端口 | `8080` |
| `--log-level <level>` | 日志级别 | `info` |
| `--log-format <format>` | 日志格式 (`json`/`text`) | `text` |

### 传输协议选项

| 参数 | 描述 | 默认值 |
|------|------|--------|
| `--transport <name>` | 传输协议 (`stdio`/`sse`/`streamable-http`) | `stdio` |
| `--session-idle-timeout-minutes <minutes>` | 空闲会话超时时间 | `30` |

### Grafana 连接选项

| 参数 | 描述 |
|------|------|
| `--grafana-url <url>` | Grafana URL |
| `--grafana-token <token>` | 服务账户令牌 |
| `--grafana-auth <user:pass>` | Basic 认证凭证 |

详细参数说明参见：[configure/command-line-flags.md](https://github.com/grafana/mcp-grafana/blob/main/docs/sources/configure/command-line-flags.md)

## 传输协议配置

Grafana MCP Server 支持多种传输协议，适用于不同的使用场景：

```mermaid
graph TD
    A[客户端] --> B{传输协议选择}
    B --> C[stdio]
    B --> D[SSE]
    B --> E[streamable-http]
    
    C --> F[本地进程通信]
    D --> G[Server-Sent Events]
    E --> H[HTTP 长连接流式响应]
    
    F --> I[适用于 MCP SDK 客户端]
    G --> J[适用于 Web 应用]
    H --> K[适用于现代 Web 应用]
```

### STDIO 模式（默认）

适用于 MCP SDK 客户端直接连接：

```bash
mcp-grafana --transport stdio
```

### SSE 模式

适用于需要 Web 前端访问的场景，支持通过 HTTP 长连接接收服务端推送：

```bash
mcp-grafana --transport sse --host 0.0.0.0 --port 8080
```

SSE 模式下支持转发请求头（如 `Cookie`、`Authorization`），可实现 SSO 和 ALB 会话 cookie 认证。资料来源：[transports-and-addresses.md](https://github.com/grafana/mcp-grafana/blob/main/docs/sources/configure/transports-and-addresses.md)

### Streamable HTTP 模式

现代 Web 应用推荐使用，支持流式响应和更好的兼容性：

```bash
mcp-grafana --transport streamable-http --host 0.0.0.0 --port 8080
```

## 认证配置

### 服务账户令牌（推荐）

创建 Grafana 服务账户并生成令牌：

1. 登录 Grafana → **Administration** → **Service Accounts**
2. 创建新服务账户
3. 生成令牌并复制
4. 配置环境变量或命令行参数

```bash
export GRAFANA_TOKEN="glsa_xxxxxxxxxxxxx"
```

> **注意**：创建服务账户通常需要较高的权限。对于普通用户而言，这种方式可能不够便捷。相关讨论参见 [Issue #151](https://github.com/grafana/mcp-grafana/issues/151)。

### Basic 认证

支持传统的用户名密码认证：

```bash
export GRAFANA_AUTH="admin:admin"
```

### OAuth/SSO 支持

当前版本对 OAuth/SSO 的支持有限。社区请求参见 [Issue #284](https://github.com/grafana/mcp-grafana/issues/284)，该问题涉及以下场景：

- Okta 集成
- Google OAuth
- Azure AD

v0.11.5 版本增加了对 `Cookie` 和 `Authorization` 请求头的转发支持，可在 SSE 和 streamable-http 模式下启用 SSO 认证。资料来源：[transports-and-addresses.md](https://github.com/grafana/mcp-grafana/blob/main/docs/sources/configure/transports-and-addresses.md)

## 客户端配置示例

### Claude Desktop 配置

```json
{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": ["--transport", "stdio"],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_TOKEN": "glsa_xxxxxxxxxxxxx"
      }
    }
  }
}
```

### Cursor IDE 配置

```json
{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": ["run", "--rm", "-i", 
               "-e", "GRAFANA_URL=http://host.docker.internal:3000",
               "-e", "GRAFANA_TOKEN=${GRAFANA_TOKEN}",
               "mcp/grafana"]
    }
  }
}
```

详细配置示例参见：[set-up/client-configuration-examples.md](https://github.com/grafana/mcp-grafana/blob/main/docs/sources/set-up/client-configuration-examples.md)

## 配置加载顺序

Grafana MCP Server 按以下优先级加载配置：

```mermaid
graph LR
    A[命令行参数] --> B[最高优先级]
    C[环境变量] --> D[中等优先级]
    E[配置文件] --> F[最低优先级]
    G[默认值] --> H[兜底配置]
    
    style B fill:#ff9999
    style D fill:#ffcc99
    style F fill:#ffff99
    style H fill:#99ff99
```

## 日志配置

### 日志级别

| 级别 | 描述 |
|------|------|
| `debug` | 详细调试信息 |
| `info` | 一般信息（默认） |
| `warn` | 警告信息 |
| `error` | 错误信息 |

### 日志格式

支持两种日志格式：

- `text`：人类可读的文本格式
- `json`：结构化 JSON 格式，适合日志收集系统

v0.12.1 版本增加了可选的 `Logger` 字段用于结构化日志记录。资料来源：[cmd/mcp-grafana/main.go](https://github.com/grafana/mcp-grafana/blob/main/cmd/mcp-grafana/main.go)

## 常见问题

### Q: Docker 镜像没有版本标签怎么办？

目前 Docker Hub 上的镜像只有 `latest` 标签，无法指定特定版本。建议在 `docker-compose.yml` 中锁定镜像 SHA256 摘要以确保版本一致性。

### Q: 如何在多组织环境下工作？

Grafana MCP 支持跨组织操作，但需确保服务账户具有相应权限。v0.11.6 版本增强了 on-behalf-of 认证头支持。

### Q: 连接失败如何排查？

1. 确认 Grafana 实例可访问
2. 验证令牌/认证凭证有效
3. 检查日志级别是否足够详细
4. 确认防火墙和网络配置

---

<a id='authentication'></a>

## 认证与授权

### 相关页面

相关主题：[仪表板工具](#dashboard-tools), [故障排除与常见问题](#troubleshooting)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docs/sources/configure/authentication.md](https://github.com/grafana/mcp-grafana/blob/main/docs/sources/configure/authentication.md)
- [docs/sources/configure/multi-organization-and-headers.md](https://github.com/grafana/mcp-grafana/blob/main/docs/sources/configure/multi-organization-and-headers.md)
- [client_cache.go](https://github.com/grafana/mcp-grafana/blob/main/client_cache.go)
- [session.go](https://github.com/grafana/mcp-grafana/blob/main/session.go)
- [transport.go](https://github.com/grafana/mcp-grafana/blob/main/transport.go)
</details>

# 认证与授权

## 概述

mcp-grafana 的认证与授权系统负责管理 MCP Server 与 Grafana 实例之间的安全连接。该系统支持多种认证方式，包括服务账号令牌、基本认证和 SSO 会话认证，并提供了多组织支持和请求上下文传播机制。

## 认证方式

mcp-grafana 支持以下几种认证方式：

| 认证方式 | 配置字段 | 说明 |
|---------|---------|------|
| 服务账号令牌 | `GRAFANA_AUTH_TOKEN` | 推荐的生产环境认证方式 |
| 基本认证 | `GRAFANA_AUTH_USER` / `GRAFANA_AUTH_PASSWORD` | 适用于开发和测试环境 |
| SSO 会话认证 | `forwardAuthHeaders` 或请求头转发 | 适用于使用 SSO 或负载均衡器的生产环境 |

### 服务账号令牌认证

服务账号令牌是最推荐的认证方式，适用于生产环境。使用步骤：

1. 在 Grafana 中创建服务账号
2. 为服务账号分配必要的角色和权限
3. 生成 API 密钥
4. 通过环境变量 `GRAFANA_AUTH_TOKEN` 配置

```bash
export GRAFANA_AUTH_TOKEN="glsa_xxxxxx"
```

### 基本认证

基本认证使用用户名和密码组合：

```bash
export GRAFANA_AUTH_USER="admin"
export GRAFANA_AUTH_PASSWORD="your-password"
```

> ⚠️ 注意：许多组织已禁用 Grafana 的基本认证，此时必须使用服务账号令牌或 SSO 认证。

### SSO 与负载均衡器会话认证

在 v0.11.5 中引入的请求头转发功能，支持通过 SSO 或应用负载均衡器（ALB）进行认证。

## 多组织支持

mcp-grafana 支持在多个 Grafana 组织之间工作，适用于需要跨组织访问资源的场景。

### 工作机制

```mermaid
graph TD
    A[MCP Client] --> B[MCP Server]
    B --> C[Client Cache]
    C --> D{Grafana Client<br/>per Org}
    D --> E[Org 1 Client]
    D --> F[Org 2 Client]
    D --> G[Org N Client]
    
    E --> H[Grafana API<br/>Org 1]
    F --> I[Grafana API<br/>Org 2]
    G --> J[Grafana API<br/>Org N]
```

### 组织上下文配置

每个请求可以通过以下方式指定目标组织：

| 参数 | 来源 | 说明 |
|-----|------|------|
| `orgId` | 请求参数 | 数字形式的组织 ID |
| `orgId` | 请求头 | HTTP 请求头中的组织 ID |
| `X-Grafana-Org-Id` | 请求头 | 显式指定的组织 ID 头 |

```go
// 从请求上下文中获取组织 ID
orgID := req.Context().Value("orgId")
```

## 请求头转发机制

### 支持转发的请求头

在 SSE 和 streamable-http 模式下，mcp-grafana 支持转发以下请求头：

| 请求头 | 用途 |
|-------|------|
| `Cookie` | SSO 会话 Cookie 认证 |
| `Authorization` | Bearer Token 或其他授权头 |
| `X-Grafana-Org-Id` | 目标组织指定 |

### 配置示例

```yaml
# 通过 CLI 参数启用
mcp-grafana serve --forward-auth-headers

# 或在配置文件中
server:
  forwardAuthHeaders: true
```

## 客户端缓存管理

mcp-grafana 使用客户端缓存来管理不同组织的 Grafana 客户端实例：

```mermaid
graph LR
    A[请求进入] --> B{检查缓存}
    B -->|存在| C[返回缓存客户端]
    B -->|不存在| D[创建新客户端]
    D --> E[缓存客户端]
    C --> F[执行请求]
    E --> F
    F --> G[返回结果]
```

### 缓存键生成

客户端缓存使用以下组合键：

- 目标 URL
- 认证信息（令牌或用户/密码）
- 组织 ID

```go
type clientCacheKey struct {
    url        string
    authToken  string
    authUser   string
    authPass   string
    orgID      int64
}
```

## 身份委托

在 v0.11.6 中引入的身份委托功能允许在请求链中传播认证上下文。

### 工作原理

```mermaid
graph TD
    A[原始请求] --> B[RoundTripper Chain]
    B --> C[身份委托头添加]
    C --> D[Grafana API 请求]
    D --> E[验证身份]
    E --> F{授权结果}
    F -->|通过| G[返回数据]
    F -->|拒绝| H[返回 403]
```

### 适用场景

- 代理场景下的身份传播
- 多租户环境下的委托认证
- 审计日志中的身份追溯

## 环境变量配置

| 变量名 | 必填 | 说明 |
|-------|-----|------|
| `GRAFANA_URL` | 是 | Grafana 服务器地址 |
| `GRAFANA_AUTH_TOKEN` | 是* | 服务账号 API 密钥 |
| `GRAFANA_AUTH_USER` | 是* | 基本认证用户名 |
| `GRAFANA_AUTH_PASSWORD` | 是* | 基本认证密码 |
| `GRAFANA_ORG_ID` | 否 | 默认组织 ID |

> *：`GRAFANA_AUTH_TOKEN` 或 `GRAFANA_AUTH_USER`+`GRAFANA_AUTH_PASSWORD` 二选一

## 安全最佳实践

### 生产环境建议

1. **优先使用服务账号令牌**：避免在生产环境使用基本认证
2. **最小权限原则**：为服务账号分配最小必要权限
3. **启用请求头转发时注意安全**：确保上游代理已正确验证身份
4. **敏感信息加密存储**：不要将认证信息明文存储在配置文件中

### 常见问题排查

| 问题 | 可能原因 | 解决方案 |
|-----|---------|---------|
| 401 Unauthorized | 令牌无效或过期 | 检查 `GRAFANA_AUTH_TOKEN` 配置 |
| 403 Forbidden | 权限不足 | 检查服务账号角色配置 |
| 跨组织请求失败 | 未指定 orgId | 添加 `X-Grafana-Org-Id` 请求头 |

## 相关资源

- 配置文档：[docs/sources/configure/authentication.md](docs/sources/configure/authentication.md)
- 多组织配置：[docs/sources/configure/multi-organization-and-headers.md](docs/sources/configure/multi-organization-and-headers.md)
- GitHub Issue #284：[OAuth/SSO 认证功能请求](https://github.com/grafana/mcp-grafana/issues/284)
- GitHub Issue #151：[普通用户工作流程讨论](https://github.com/grafana/mcp-grafana/issues/151)

---

<a id='deployment'></a>

## 部署与运维

### 相关页面

相关主题：[安装与配置](#installation), [故障排除与常见问题](#troubleshooting)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [Dockerfile](https://github.com/grafana/mcp-grafana/blob/main/Dockerfile)
- [Dockerfile.alpine](https://github.com/grafana/mcp-grafana/blob/main/Dockerfile.alpine)
- [docs/sources/set-up/deploy-with-helm.md](https://github.com/grafana/mcp-grafana/blob/main/docs/sources/set-up/deploy-with-helm.md)
- [docs/sources/configure/server-tls-streamable-http.md](https://github.com/grafana/mcp-grafana/blob/main/docs/sources/configure/server-tls-streamable-http.md)
- [session_horizontal_scaling_test.go](https://github.com/grafana/mcp-grafana/blob/main/session_horizontal_scaling_test.go)
</details>

# 部署与运维

## 概述

`mcp-grafana` 支持多种部署方式，包括 Docker 容器化部署、Helm Chart 部署以及直接二进制运行。部署与运维模块负责处理服务的生命周期管理、安全配置、会话状态管理和水平扩展能力。

本模块的核心职责包括：
- 提供生产级别的 Docker 镜像
- 支持 Kubernetes 环境下的 Helm Chart 部署
- 配置 TLS 加密传输
- 管理多实例会话状态
- 支持 SSE 和 Streamable-HTTP 等高级传输模式

## 部署方式

### Docker 容器部署

`mcp-grafana` 提供两种 Docker 镜像变体以满足不同场景需求：

| 镜像变体 | 基础镜像 | 大小 | 适用场景 |
|---------|---------|------|---------|
| 标准版 | `debian:bookworm-slim` | 较大 | 追求稳定性的生产环境 |
| Alpine 版 | `alpine:3.20` | 较小 | 资源受限环境或追求最小镜像 |

Alpine 版本镜像采用多阶段构建优化体积，同时通过显式安装 CA 证书确保 HTTPS 连接正常：

```dockerfile
# Dockerfile.alpine 核心构建逻辑
FROM alpine:3.20 AS base
RUN apk add --no-cache \
    ca-certificates \
    tzdata

FROM alpine:3.20
COPY --from=base /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --from=build /app/mcp-grafana /app/mcp-grafana
```

标准版 Dockerfile 使用 `debian:bookworm-slim` 作为基础镜像，通过 `gosu` 处理非 root 用户权限：

```dockerfile
# Dockerfile 入口点配置
COPY --from=base /etc/passwd /etc/passwd
RUN chmod 444 /etc/passwd

USER 1000
WORKDIR /app
ENTRYPOINT ["/app/mcp-grafana"]
```

镜像默认以非 root 用户 `1000:0` 运行，保障容器安全性。 资料来源：[Dockerfile:24-31]()

### Helm Chart 部署

对于 Kubernetes 环境，`mcp-grafana` 提供完整的 Helm Chart 支持。部署时可通过 `values.yaml` 配置各项参数：

```yaml
# 基础配置示例
image:
  repository: grafana/mcp-grafana
  tag: latest
  pullPolicy: IfNotPresent

replicaCount: 1

env:
  - name: GRAFANA_URL
    value: "https://grafana.example.com"
  - name: GRAFANA_TOKEN
    valueFrom:
      secretKeyRef:
        name: grafana-credentials
        key: token
```

Helm 部署支持完整的 Kubernetes 原生特性：
- **ConfigMap/Secret 注入**：通过 `extraEnv` 或 `extraEnvFrom` 注入环境变量
- **健康检查**：自动配置 liveness 和 readiness probes
- **资源限制**：通过 `resources.limits` 和 `resources.requests` 控制资源分配
- **亲和性调度**：支持 `nodeAffinity`、`podAffinity` 等高级调度策略

资料来源：[docs/sources/set-up/deploy-with-helm.md]()

## 安全传输配置

### TLS 与 Streamable-HTTP

`mcp-grafana` 支持通过 TLS 加密保护 MCP 通信。服务启动时通过命令行参数配置 TLS：

```bash
mcp-grafana serve-tls \
  --host 0.0.0.0 \
  --port 8443 \
  --cert /path/to/server.crt \
  --key /path/to/server.key
```

Streamable-HTTP 模式下，TLS 配置需要与应用层传输选项配合：

| 参数 | 说明 | 默认值 |
|-----|------|-------|
| `--transport` | 传输类型 (stdio/sse/streamable-http) | stdio |
| `--port` | HTTP 服务监听端口 | 8080 |
| `--host` | 监听地址 | 127.0.0.1 |
| `--tls-cert` | TLS 证书路径 | - |
| `--tls-key` | TLS 私钥路径 | - |

SSE 模式下支持转发认证相关的请求头（如 `Cookie`、`Authorization`），这对 SSO 和 ALB 会话 Cookie 认证至关重要。 资料来源：[docs/sources/configure/server-tls-streamable-http.md]()

## 会话管理

### 水平扩展架构

`mcp-grafana` 设计支持多实例水平扩展。核心架构基于会话 ID 标识和路由机制：

```mermaid
graph TD
    A[Client A] -->|Session-ID: abc123| LB[负载均衡器]
    B[Client B] -->|Session-ID: def456| LB
    C[Client C] -->|Session-ID: abc123| LB
    
    LB -->|粘性会话| S1[Instance 1]
    LB -->|粘性会话| S2[Instance 2]
    
    S1 -->|处理 abc123| DB[(Redis<br/>会话存储)]
    S2 -->|处理 def456| DB
    
    S1 -.->|状态同步| DB
    S2 -.->|状态同步| DB
```

会话测试文件定义了水平扩展的验证场景：

```go
// session_horizontal_scaling_test.go
func TestSessionAffinity(t *testing.T) {
    // 验证相同 Session-ID 的请求被路由到同一实例
    // 验证不同 Session-ID 的请求可分配到不同实例
}
```

资料来源：[session_horizontal_scaling_test.go]()

### 会话空闲超时

服务支持配置会话空闲超时，自动清理长期未活跃的会话资源：

| 参数 | 说明 | 默认值 |
|-----|------|-------|
| `--session-idle-timeout-minutes` | 会话空闲超时时间（分钟） | 30 |

此特性在 v0.11.4 版本引入，帮助在长时间运行的 MCP 服务器中释放资源。

## 配置参考

### 完整环境变量列表

| 变量名 | 说明 | 必需 |
|-------|------|-----|
| `GRAFANA_URL` | Grafana 实例地址 | 是 |
| `GRAFANA_TOKEN` | Service Account Token | 是 |
| `LOG_LEVEL` | 日志级别 (debug/info/warn/error) | 否 |
| `LOG_FORMAT` | 日志格式 (json/text) | 否 |

### 健康检查端点

在 SSE 和 Streamable-HTTP 模式下，服务提供健康检查端点：

```bash
# Liveness Probe
curl http://localhost:8080/healthz

# Readiness Probe  
curl http://localhost:8080/ready
```

## 社区相关议题

部署与运维相关的社区热点问题包括：

- **#180 Docker 镜像版本标签**：用户请求为 Docker Hub 上的镜像添加版本标签而非仅 `latest`，便于精确版本控制
- **#151 普通用户工作流程**：社区讨论 MCP 服务器对普通用户的适用性，涉及认证方式的改进需求
- **#284 OAuth/SSO 认证支持**：高优先级功能请求，希望支持 Okta、Google OAuth、Azure AD 等 SSO 提供商

## 故障排查

### 常见部署问题

| 问题 | 可能原因 | 解决方案 |
|-----|---------|---------|
| 连接被拒绝 | 端口未正确映射 | 检查 `-p` 参数映射是否正确 |
| TLS 握手失败 | 证书格式错误 | 确认使用 PEM 编码的证书和私钥 |
| 会话丢失 | 负载均衡器未配置会话亲和 | 配置基于 Session-ID 的 sticky session |
| 镜像拉取失败 | 网络或认证问题 | 配置 imagePullSecrets |

### 日志调试

启用调试日志有助于排查部署问题：

```bash
# 启用调试模式
mcp-grafana serve --log-level debug

---

<a id='dashboard-tools'></a>

## 仪表板工具

### 相关页面

相关主题：[数据源工具](#datasource-tools), [查询执行工具](#query-tools)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [tools/dashboard.go](https://github.com/grafana/mcp-grafana/blob/main/tools/dashboard.go)
- [tools/dashboard_helpers.go](https://github.com/grafana/mcp-grafana/blob/main/tools/dashboard_helpers.go)
- [tools/navigation.go](https://github.com/grafana/mcp-grafana/blob/main/tools/navigation.go)
- [tools/rendering.go](https://github.com/grafana/mcp-grafana/blob/main/tools/rendering.go)
</details>

# 仪表板工具

仪表板工具是 Grafana MCP (Model Context Protocol) 插件中用于与 Grafana 仪表板资源交互的核心功能模块。这些工具提供了仪表板检索、面板查询提取、深度链接生成、面板图像渲染以及导航等多种能力，使 LLM 能够有效地查询和操作 Grafana 仪表板资源。

## 工具概览

仪表板工具集涵盖了从基本的仪表板读取到高级的渲染和导航功能。根据社区反馈和版本发布记录，这些工具经历了多次增强，包括面板过滤、模板变量替换、多组织支持等功能。

### 核心工具列表

| 工具名称 | 功能描述 | 首次引入版本 |
|---------|---------|-------------|
| `get_dashboard` | 获取单个仪表板详情 | 早期版本 |
| `get_dashboards` | 批量搜索和检索仪表板 | 早期版本 |
| `get_dashboard_panel_queries` | 提取面板查询并支持模板变量替换 | v0.11.3 |
| `get_panel_image` | 渲染面板为图像 | 早期版本 |
| `generate_deeplink` | 生成 Grafana 深度链接 URL | 早期版本 |
| `create_short_url` | 创建短 URL | v0.14.0 |

## 仪表板查询工具

### get_dashboard

`get_dashboard` 工具用于根据仪表板的唯一标识符 (UID) 检索完整的仪表板定义。该工具返回仪表板的完整 JSON 结构，包括所有面板、行、查询配置以及变量定义。

```mermaid
graph TD
    A[调用 get_dashboard] --> B[验证 UID 参数]
    B --> C[调用 Grafana API /api/dashboards/uid/{uid}]
    C --> D{请求成功?}
    D -->|是| E[返回仪表板 JSON 结构]
    D -->|否| F[返回错误信息]
```

#### 输入参数

| 参数名 | 类型 | 必需 | 描述 |
|-------|------|------|------|
| `uid` | string | 是 | 仪表板的唯一标识符 |
| `orgId` | number | 否 | 组织 ID，用于多组织环境 |

根据社区反馈（issue #883），在多组织场景下，`get_dashboard` 工具能够正确处理不同组织的仪表板访问权限，但面板图像渲染功能曾存在 `orgId` 支持不完整的问题。

### get_dashboards

`get_dashboards` 工具提供了更灵活的仪表板搜索能力，支持基于标签、文件夹和其他条件的筛选查询。

#### 输入参数

| 参数名 | 类型 | 必需 | 描述 |
|-------|------|------|------|
| `limit` | number | 否 | 返回结果数量上限，默认值由配置决定 |
| `tags` | string[] | 否 | 按标签筛选仪表板 |
| `folderUID` | string | 否 | 指定文件夹内的仪表板 |
| `query` | string | 否 | 基于仪表板名称的模糊搜索 |
| `orgId` | number | 否 | 组织 ID |

该工具的实现位于 `tools/dashboard.go` 中，调用 Grafana 的仪表板搜索 API 并对结果进行后处理以适配 MCP 协议。

## 面板查询工具

### get_dashboard_panel_queries

`get_dashboard_panel_queries` 是 v0.11.3 版本新增的重要功能，它能够从仪表板中提取指定面板的查询配置，并支持模板变量替换。

```mermaid
graph TD
    A[输入: dashboardUID + panelID] --> B[获取仪表板定义]
    B --> C[定位目标面板]
    C --> D[应用模板变量替换?]
    D -->|是| E[替换变量占位符]
    D -->|否| F[保持原始查询]
    E --> G[返回查询配置列表]
    F --> G
```

#### 功能特性

- **面板过滤**：通过面板 ID 精确定位目标面板
- **模板变量替换**：自动将 Grafana 变量占位符替换为实际值
- **多查询支持**：返回面板中定义的所有查询（支持混合数据源）

#### 输入参数

| 参数名 | 类型 | 必需 | 描述 |
|-------|------|------|------|
| `dashboardUID` | string | 是 | 仪表板唯一标识符 |
| `panelId` | number | 是 | 面板 ID |
| `variableOverrides` | object | 否 | 变量名到值的映射，用于覆盖默认值 |

根据 v0.11.3 发行说明，该工具显著提升了 LLM 工作流中查询提取的精确度，减少了不必要的全仪表板查询。

## 渲染工具

### get_panel_image

`get_panel_image` 工具将 Grafana 面板渲染为图像，便于在报告、文档或聊天界面中展示可视化结果。

#### 输入参数

| 参数名 | 类型 | 必需 | 描述 |
|-------|------|------|------|
| `panelId` | number | 是 | 面板 ID |
| `dashboardUID` | string | 是 | 仪表板唯一标识符 |
| `orgId` | number | 否 | 组织 ID |
| `width` | number | 否 | 图像宽度（像素） |
| `height` | number | 否 | 图像高度（像素） |
| `timeout` | number | 否 | 渲染超时时间（秒） |

#### 已知限制

社区反馈（issue #883）指出 `get_panel_image` 在 v0.13.x 版本中存在 `orgId` 支持不完整的问题。当在多组织环境中使用时，面板渲染可能回退到默认组织而非指定组织。这影响了跨组织仪表板资源访问的完整性。

v0.12.0 版本增加了对传统 `d-solo` 渲染模式的支持，以保持向后兼容性。

## 导航与深度链接工具

### generate_deeplink

`generate_deeplink` 工具为仪表板和面板生成可直接访问的 Grafana URL，支持跳转到特定时间范围和数据视图。

#### 输入参数

| 参数名 | 类型 | 必需 | 描述 |
|-------|------|------|------|
| `panelId` | number | 是 | 面板 ID |
| `dashboardUID` | string | 是 | 仪表板唯一标识符 |
| `timeRange` | object | 否 | 指定时间范围 |
| `queries` | object[] | 否 | 预定义的查询参数 |

#### URL 生成逻辑

生成的 URL 遵循 Grafana Explore 或仪表板标准格式，包含以下关键参数：

- `from` / `to`：时间范围（支持 ISO 8601 和 epoch 毫秒格式，v0.13.0 修复了时间格式转换问题）
- `panelId`：目标面板
- `dashboardUid`：仪表板标识
- `left`：编码的查询窗格 JSON（包含数据源和查询表达式）

### create_short_url

`create_short_url` 是 v0.14.0 版本引入的工具，用于创建 Grafana 短 URL（`/goto/<uid>` 格式）。

#### 问题背景

根据 issue #820 的反馈，`generate_deeplink` 生成的完整 Explore URL 包含大量 URL 编码的 JSON 数据，特别是对于复杂的 LogQL/PromQL 查询，URL 长度可能达到数百字符。这导致：

- 在聊天消息中难以阅读和分享
- 难以作为 LLM 响应的可点击链接
- 复制粘贴操作繁琐

#### 解决方案

短 URL API (`/api/short-urls`) 接收完整 URL 并返回简短的 `/goto/<uid>` 格式别名，显著提升可用性。

#### 输入参数

| 参数名 | 类型 | 必需 | 描述 |
|-------|------|------|------|
| `path` | string | 是 | 原始 Grafana URL 路径（不含域名） |

#### 输出格式

```json
{
  "url": "/goto/Abc123XYZ",
  "uid": "Abc123XYZ"
}
```

## 数据流架构

```mermaid
graph LR
    A[MCP Client] -->|工具调用| B[tools/dashboard.go]
    A -->|工具调用| C[tools/rendering.go]
    A -->|工具调用| D[tools/navigation.go]
    
    B -->|HTTP 请求| E[Grafana API]
    C -->|HTTP 请求| E
    D -->|HTTP 请求| E
    
    E -->|JSON 响应| F[响应格式化]
    F -->|MCP 协议| A
    
    G[模板变量引擎] -.->|变量替换| B
    H[图像渲染服务] -.->|PNG 输出| C
```

## 错误处理与边界情况

### 常见错误场景

| 错误类型 | 原因 | 处理方式 |
|---------|------|---------|
| 仪表板未找到 | 无效 UID 或权限不足 | 返回 `RESOURCE_NOT_FOUND` 错误 |
| 面板不存在 | panelId 不匹配 | 返回具体面板 ID 错误 |
| 渲染超时 | 查询执行时间过长 | 支持配置超时时间 |
| 组织不匹配 | 跨组织访问限制 | 返回认证错误 |

### 类型兼容性

v0.13.0 版本修复了 LLM 常见类型不匹配问题，例如字符串与数字的混淆，这些问题曾导致 `alerting_manage_rules` 工具调用失败。仪表板工具也受益于类似的类型验证增强。

## 配置与认证

仪表板工具依赖 Grafana MCP 的基础配置，包括：

- **Grafana URL**：Grafana 服务器地址
- **认证方式**：服务账户令牌或基本认证（参见 issue #284 关于 OAuth/SSO 支持的需求）
- **组织上下文**：通过 `X-Grafana-Org-Id` 头或 `orgId` 参数指定

v0.11.6 版本实现的代理身份认证头部机制允许在仪表板操作中传递委托身份信息。

## 最佳实践

### 查询优化

对于需要频繁访问的仪表板，建议：

1. 使用 `get_dashboard` 获取完整定义后缓存结果
2. 使用 `get_dashboard_panel_queries` 提取单个面板查询而非加载整个仪表板
3. 在时间关键场景中使用 `get_panel_image` 而非实时查询

### 多组织环境

在多组织部署中：

1. 显式传递 `orgId` 参数
2. 注意 `get_panel_image` 的组织限制（issue #883）
3. 使用短 URL 共享跨组织资源

### 图像渲染

面板图像渲染的最佳实践：

- 设置合理的 `timeout` 值（默认 30 秒）
- 根据展示需求调整 `width` 和 `height`
- v0.12.0+ 版本支持传统 `d-solo` 模式以确保兼容性

## 相关资源

- 源代码：[tools/dashboard.go](https://github.com/grafana/mcp-grafana/blob/main/tools/dashboard.go)
- 辅助函数：[tools/dashboard_helpers.go](https://github.com/grafana/mcp-grafana/blob/main/tools/dashboard_helpers.go)
- 渲染实现：[tools/rendering.go](https://github.com/grafana/mcp-grafana/blob/main/tools/rendering.go)
- 导航工具：[tools/navigation.go](https://github.com/grafana/mcp-grafana/blob/main/tools/navigation.go)
- 社区问题： [#820](https://github.com/grafana/mcp-grafana/issues/820)（短 URL 功能）、[#883](https://github.com/grafana/mcp-grafana/issues/883)（orgId 支持）

---

<a id='datasource-tools'></a>

## 数据源工具

### 相关页面

相关主题：[查询执行工具](#query-tools), [仪表板工具](#dashboard-tools)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [tools/datasources.go](https://github.com/grafana/mcp-grafana/blob/main/tools/datasources.go)
- [tools/ds_query.go](https://github.com/grafana/mcp-grafana/blob/main/tools/ds_query.go)
- [tools/snowflake.go](https://github.com/grafana/mcp-grafana/blob/main/tools/snowflake.go)
- [tools/athena.go](https://github.com/grafana/mcp-grafana/blob/main/tools/athena.go)
- [tools/clickhouse.go](https://github.com/grafana/mcp-grafana/blob/main/tools/clickhouse.go)
</details>

# 数据源工具

数据源工具是 Grafana MCP (Model Context Protocol) 服务器的核心功能模块，提供与 Grafana 数据源交互的标准化接口。通过这些工具，用户可以在 MCP 客户端（如 Claude Code）中直接查询、可视化和分析来自多种数据源的数据。

## 功能概述

MCP Grafana 的数据源工具支持以下核心能力：

- **多数据源统一查询**：通过 `ds_query` 工具向任意 Grafana 配置的数据源发送查询请求
- **数据源发现与管理**：列出可用数据源、获取数据源详情
- **专用数据源工具**：针对特定数据源优化的查询工具（Snowflake、Athena、ClickHouse 等）
- **模式发现**：支持从某些数据源获取 schema 信息

### 支持的数据源类型

根据版本发布记录，MCP Grafana 支持以下数据源：

| 数据源 | 支持版本 | 查询语言/方式 | 备注 |
|--------|----------|---------------|------|
| Prometheus | v0.11.0+ | PromQL | 支持 VictoriaMetrics |
| Loki | v0.11.0+ | LogQL | 支持分页请求 |
| InfluxDB | v0.12.0+ | Flux/InfluxQL | v0.12.0 新增 |
| Graphite | v0.12.0+ | 树形查询 | v0.12.0 新增 |
| OpenSearch | v0.14.0+ | Lucene 查询 | v0.14.0 新增 |
| Snowflake | v0.15.0+ | SQL | v0.15.0 新增 |
| Amazon Athena | v0.15.0+ | SQL | v0.15.0 新增 |
| Cloud Monitoring | v0.11.5+ | MQL | 支持 projectName 参数 |
| Pyroscope | v0.11.4+ | Profiling 查询 | v0.11.4 新增 |

## 核心工具

### ds_query - 通用数据源查询

`ds_query` 是最核心的通用查询工具，通过 Grafana 的 `/api/ds/query` 端点转发查询请求到任意已配置的数据源。

#### 功能特点

- 支持所有在 Grafana 中配置的数据源
- 自动处理 Grafana 的查询 API 协议
- 支持模板变量替换
- 支持时间范围指定
- 支持宏替换（部分数据源）

#### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| queries | array | 是 | 查询对象数组 |
| queries[].refId | string | 是 | 查询引用 ID |
| queries[].datasourceUid | string | 是 | 数据源 UID |
| queries[].type | string | 是 | 查询类型（如 `prometheus`, `loki`） |
| queries[].expr | string | 否 | PromQL/LogQL 表达式 |
| queries[].query | string | 否 | SQL 查询语句 |
| queries[].intervalMs | number | 否 | 间隔（毫秒） |
| queries[].maxDataPoints | number | 否 | 最大数据点数 |

### datasources - 数据源管理

`datasources` 工具提供数据源的发现和管理功能。

#### 可用操作

| 操作 | 说明 |
|------|------|
| list | 列出所有已配置的数据源 |
| get | 根据 UID 获取单个数据源详情 |

#### 数据源详情返回字段

| 字段 | 说明 |
|------|------|
| uid | 数据源唯一标识符 |
| name | 数据源名称 |
| type | 数据源类型（prometheus, influxdb 等） |
| url | 数据源 URL |
| access | 访问模式（proxy/direct） |
| isDefault | 是否为默认数据源 |
| jsonData | JSON 格式的连接配置 |
| secureJsonData | 加密的敏感配置（不包含实际值） |

## 专用数据源工具

### Snowflake 查询工具

v0.15.0 新增的 Snowflake 专用工具，提供优化的 SQL 查询体验。

#### 核心功能

- 通过 Grafana Snowflake 数据源执行查询
- 支持宏替换（`$__from`, `$__to`, `$__table` 等）
- 支持模板变量
- 支持查询结果缓存/复用

#### 宏变量支持

| 宏变量 | 说明 |
|--------|------|
| `$__from` | 查询起始时间 |
| `$__to` | 查询结束时间 |
| `$__table` | 表名宏 |
| `$__column` | 列名宏 |

### Amazon Athena 查询工具

v0.15.0 新增的 Athena 专用工具，支持 AWS Athena 数据源。

#### 核心功能

- Schema 发现：列出数据库、表和分区
- SQL 查询执行
- 宏替换支持
- 查询结果复用

#### Schema 发现

| 操作 | 说明 |
|------|------|
| list_catalogs | 列出所有 AWS Glue 目录 |
| list_databases | 列出指定目录中的数据库 |
| list_tables | 列出指定数据库中的表 |
| list_table_metadata | 获取表的列和分区信息 |

### ClickHouse 查询工具

ClickHouse 数据源专用工具，支持该流行列式数据库的查询。

## 数据流架构

```mermaid
graph TD
    A[MCP 客户端] -->|工具调用| B[MCP Grafana 服务器]
    B -->|ds_query 请求| C[Grafana API]
    C -->|/api/ds/query| D[数据源插件]
    D -->|查询| E[数据源]
    
    F[专用工具] -->|标准化请求| C
    G[模板变量替换] -->|处理| F
    
    E -->|查询结果| D
    D -->|格式化数据| C
    C -->|JSON 响应| B
    B -->|结构化结果| A
```

## 查询执行流程

```mermaid
sequenceDiagram
    participant Client as MCP 客户端
    participant Server as MCP 服务器
    participant Grafana as Grafana API
    participant DS as 数据源
    
    Client->>Server: ds_query(queries)
    Server->>Server: 验证查询参数
    Server->>Server: 替换模板变量
    Server->>Grafana: POST /api/ds/query
    Grafana->>DS: 转发查询
    DS-->>Grafana: 查询结果
    Grafana-->>Server: 格式化响应
    Server-->>Client: 返回查询结果
```

## 常见使用场景

### 场景一：Prometheus 指标查询

```json
{
  "queries": [{
    "refId": "A",
    "datasourceUid": "prometheus-uid",
    "type": "prometheus",
    "expr": "rate(http_requests_total[5m])",
    "intervalMs": 5000,
    "maxDataPoints": 1000
  }]
}
```

### 场景二：Loki 日志查询

```json
{
  "queries": [{
    "refId": "A",
    "datasourceUid": "loki-uid",
    "type": "range",
    "expr": "{namespace=\"prod\"} |= \"error\"",
    "queryType": "instant"
  }]
}
```

### 场景三：Snowflake 数据分析

```sql
SELECT 
  $__column(date, created_at),
  COUNT(*) as cnt
FROM $__table
WHERE $__from AND $__to
GROUP BY date
```

## 配置与最佳实践

### 数据源配置要求

1. **Grafana 端配置**：确保数据源已在 Grafana 中正确配置并测试通过
2. **权限要求**：服务账户需要 `Viewer` 或更高权限才能查询数据源
3. **跨组织支持**：使用 `orgId` 参数（部分工具支持）访问非默认组织的数据源

### 查询优化建议

| 策略 | 说明 |
|------|------|
| 限制时间范围 | 避免查询过大时间范围的数据 |
| 减少 maxDataPoints | 降低返回数据量，提高响应速度 |
| 使用模板变量 | 提高查询复用性 |
| 避免宽泛查询 | Loki 查询应使用具体标签过滤 |

## 已知限制

### 社区反馈的问题

根据 GitHub issues 社区讨论：

- **Issue #883**：`get_panel_image` 工具不支持 `orgId` 参数，导致多组织环境下面板渲染可能回退到默认组织
- **Issue #761**：Loki 日志查询结果可能过大，超过 LLM 输出处理预算，建议增加分页/分块支持
- **Issue #176**：InfluxDB 支持请求较多，现已通过 v0.12.0 实现

### 当前限制

- 部分数据源的宏变量支持因数据源类型而异
- 某些数据源不支持模板变量替换
- SQL 数据源的通用支持仍在规划中（Issue #146）

## 版本历史

| 版本 | 更新内容 |
|------|----------|
| v0.15.0 | 新增 Snowflake 和 Amazon Athena 数据源支持 |
| v0.14.0 | 新增 OpenSearch 数据源支持 |
| v0.12.0 | 新增 InfluxDB（Flux/InfluxQL）和 Graphite 数据源支持 |
| v0.11.5 | Cloud Monitoring 支持 projectName 参数 |
| v0.11.4 | 新增 Pyroscope 数据源支持 |

## 相关资源

- 源码：[tools/datasources.go](https://github.com/grafana/mcp-grafana/blob/main/tools/datasources.go)
- 通用查询：[tools/ds_query.go](https://github.com/grafana/mcp-grafana/blob/main/tools/ds_query.go)
- Snowflake 工具：[tools/snowflake.go](https://github.com/grafana/mcp-grafana/blob/main/tools/snowflake.go)
- Athena 工具：[tools/athena.go](https://github.com/grafana/mcp-grafana/blob/main/tools/athena.go)
- ClickHouse 工具：[tools/clickhouse.go](https://github.com/grafana/mcp-grafana/blob/main/tools/clickhouse.go)

---

<a id='query-tools'></a>

## 查询执行工具

### 相关页面

相关主题：[数据源工具](#datasource-tools), [告警管理工具](#alerting-tools)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [tools/prometheus.go](https://github.com/grafana/mcp-grafana/blob/main/tools/prometheus.go)
- [tools/loki.go](https://github.com/grafana/mcp-grafana/blob/main/tools/loki.go)
- [tools/loki_backend.go](https://github.com/grafana/mcp-grafana/blob/main/tools/loki_backend.go)
- [tools/influxdb.go](https://github.com/grafana/mcp-grafana/blob/main/tools/influxdb.go)
- [tools/graphite.go](https://github.com/grafana/mcp-grafana/blob/main/tools/graphite.go)
- [tools/elasticsearch.go](https://github.com/grafana/mcp-grafana/blob/main/tools/elasticsearch.go)
</details>

# 查询执行工具

## 概述

查询执行工具是 Grafana MCP 服务的核心组件，提供对 Grafana 支持的多种数据源的查询能力。这些工具通过 Grafana 的统一查询 API (`/api/ds/query`) 或各数据源原生 API 与数据源通信，实现指标查询、日志检索和事件分析等功能。

MCP-Grafana 支持的数据源包括 Prometheus、Loki、InfluxDB、Graphite、Elasticsearch 等，每种数据源都有专门的工具集来处理其特定的查询语言和返回格式。资料来源：[tools/prometheus.go:1-50]()

## 架构设计

### 查询执行流程

```mermaid
graph TD
    A[用户请求] --> B[MCP 工具调用]
    B --> C{数据源类型判断}
    C -->|Prometheus| D[prometheus.go]
    C -->|Loki| E[loki.go]
    C -->|InfluxDB| F[influxdb.go]
    C -->|Graphite| G[graphite.go]
    C -->|Elasticsearch| H[elasticsearch.go]
    D --> I[构建查询请求]
    E --> I
    F --> I
    G --> I
    H --> I
    I --> J[执行 DS Query API]
    J --> K[解析响应]
    K --> L[返回标准化结果]
```

### 核心接口

所有查询工具都遵循统一的工具定义模式，每个工具包含以下关键信息：

| 属性 | 说明 |
|------|------|
| name | 工具名称 |
| description | 工具功能描述 |
| inputSchema | JSON Schema 格式的输入参数定义 |

资料来源：[tools/prometheus.go:1-80]()

## Prometheus 查询工具

### 支持的功能

Prometheus 查询工具提供 PromQL 查询能力，支持时间序列数据的检索和分析。工具设计遵循 MCP 协议规范，支持以下核心功能：

- **范围查询**：使用 `query_range` 执行带有时间范围的查询
- **即时查询**：使用 `query_instant` 获取单一时间点的数据
- **标签查询**：通过 `query_labels` 和 `query_label_values` 获取标签信息
- **系列查询**：使用 `query_series` 获取时间序列列表
- **函数发现**：通过 `query_functions` 获取支持的 PromQL 函数列表

资料来源：[tools/prometheus.go:50-150]()

### 核心工具定义

```go
// 范围查询工具
prometheus_query_range = Tool{
    name: "prometheus_query_range",
    description: "Execute a PromQL range query against a Prometheus datasource...",
    inputSchema: {...}
}
```

工具支持以下关键参数：

| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| datasourceUID | string | 是 | Prometheus 数据源 UID |
| query | string | 是 | PromQL 查询表达式 |
| start | string | 是 | 起始时间（RFC3339 格式） |
| end | string | 是 | 结束时间（RFC3339 格式） |
| step | string | 否 | 查询步长 |

资料来源：[tools/prometheus.go:80-120]()

### VictoriaMetrics 支持

v0.13.1 版本增加了对 VictoriaMetrics 数据源的 PromQL 查询支持。通过统一的查询接口，MCP 可以透明地查询 VictoriaMetrics 后端，无需额外的配置变更。资料来源：[社区上下文 - v0.13.1]()

## Loki 日志查询工具

### 工具概览

Loki 查询工具专门用于日志检索和分析，支持 LogQL 查询语言的不同表达式类型。

```mermaid
graph LR
    A[LogQL 查询] --> B{查询类型}
    B -->|日志流| C[loki_query_logs]
    B -->|范围向量| D[loki_query_range]
    B -->|统计数据| E[loki_instant_query]
```

### 主要工具

| 工具名称 | 功能 | 适用场景 |
|----------|------|----------|
| loki_query_logs | 执行 LogQL 日志流查询 | 检索匹配的日志行 |
| loki_query_range | 范围查询，返回时间序列数据 | 指标化日志数据 |
| loki_instant_query | 即时查询，获取单一时间点数据 | 统计类查询 |
| loki_label_names | 获取所有标签名 | 探索数据结构 |
| loki_label_values | 获取指定标签的值 | 过滤条件构建 |
| loki_series | 获取序列信息 | 数据源探索 |

资料来源：[tools/loki.go:1-100]()

### 社区问题：分页支持

当前 `query_loki_logs` 返回完整的日志结果，对于大量匹配结果可能导致 JSON 响应过大，超出 LLM 输出处理预算。社区已提出分页/分块功能请求（Issue #761），建议增加结果集分页机制以支持更广泛的查询场景。资料来源：[社区上下文 - Issue #761]()

### Loki 后端查询

`loki_backend.go` 提供针对特定后端系统的查询能力，支持：
- 日志级别过滤
- 标签匹配表达式
- 时间范围控制

资料来源：[tools/loki_backend.go:1-50]()

## InfluxDB 查询工具

### 数据源特性

v0.12.0 版本引入了 InfluxDB 数据源支持，同时支持 Flux 和 InfluxQL 两种查询语言。

```mermaid
graph TD
    A[InfluxDB 查询请求] --> B{查询语言}
    B -->|Flux| C[构建 Flux 查询]
    B -->|InfluxQL| D[构建 InfluxQL 查询]
    C --> E[执行 /api/ds/query]
    D --> E
    E --> F[解析响应]
```

### 工具列表

| 工具名称 | 功能 |
|----------|------|
| influxdb_query | 执行 InfluxDB 查询 |
| influxdb_get_tags | 获取数据源标签信息 |
| influxdb_get_fields | 获取字段信息 |

资料来源：[tools/influxdb.go:1-80]()

### 社区需求

社区 Issue #176 记录了对 InfluxDB 支持的需求，期望能够查询自托管或云端的 InfluxDB 实例，执行 min、max、mean 等聚合操作。资料来源：[社区上下文 - Issue #176]()

## Graphite 查询工具

### 功能支持

v0.12.0 版本增加了 Graphite 数据源支持，提供完整的指标查询能力：

| 工具名称 | 功能 |
|----------|------|
| graphite_query | 执行 Graphite 查询 |
| graphite_get_tags | 获取指标标签 |
| graphite_get_functions | 获取支持的函数列表 |

资料来源：[tools/graphite.go:1-60]()

### 特有功能

Graphite 工具支持函数发现功能，允许动态获取数据源支持的 Graphite 函数，便于构建复杂查询。资料来源：[社区上下文 - v0.12.0]()

## Elasticsearch 查询工具

### 查询能力

Elasticsearch 工具提供对 ES 数据源的查询能力，支持：

- 日志搜索和过滤
- 聚合查询
- 索引模式发现
- 字段映射查询

```mermaid
graph LR
    A[ES 查询请求] --> B[构建 Query DSL]
    B --> C[执行 /api/ds/query]
    C --> D[解析响应]
    D --> E[返回结果]
```

### 工具定义

Elasticsearch 查询工具的 Schema 定义包含完整的参数支持，确保与 Grafana ES 数据源兼容。资料来源：[tools/elasticsearch.go:1-80]()

## 通用参数模式

### 时间范围参数

所有查询工具支持标准的时间范围参数：

| 参数 | 格式 | 说明 |
|------|------|------|
| start | RFC3339 或 Unix 时间戳 | 查询起始时间 |
| end | RFC3339 或 Unix 时间戳 | 查询结束时间 |
| from | 相对时间字符串 | 例如 "now-1h" |
| to | 相对时间字符串 | 例如 "now" |

### 数据源选择

查询请求必须指定目标数据源，通过 `datasourceUID` 参数标识 Grafana 中配置的数据源实例。

### 模板变量支持

部分工具支持模板变量替换，允许在查询中使用 Grafana 仪表板定义的变量：

```go
// 模板变量替换示例
query = strings.ReplaceAll(query, "$variable", value)
```

资料来源：[tools/loki.go:50-70]()

## 最佳实践

### 查询优化

1. **限定时间范围**：使用精确的时间范围减少返回数据量
2. **使用标签过滤**：优先使用标签匹配而非日志内容过滤
3. **选择合适的查询类型**：即时查询适用于聚合，范围查询适用于趋势分析

### 错误处理

| 错误类型 | 处理建议 |
|----------|----------|
| 数据源未找到 | 验证 datasourceUID 配置正确 |
| 查询超时 | 缩小时间范围或增加查询条件 |
| 语法错误 | 检查 PromQL/LogQL 语法 |

### 性能考虑

- 避免全量数据查询，使用时间窗口分批获取
- 复杂查询考虑预聚合或录制规则
- Loki 查询注意避免高基数标签组合

## 相关资源

- Grafana 数据源文档：https://grafana.com/docs/grafana/latest/datasources/
- Prometheus 查询文档：https://prometheus.io/docs/prometheus/latest/querying/
- LogQL 语法参考：https://grafana.com/docs/loki/latest/logql/

## 社区反馈

以下社区问题与查询执行工具直接相关：

| Issue | 描述 | 优先级 |
|-------|------|--------|
| #761 | Loki 日志查询分页需求 | 高 |
| #176 | InfluxDB 数据源支持 | 已实现 |
| #146 | SQL 数据源支持请求 | 待处理 |

持续关注社区反馈以了解查询功能的演进方向。

---

<a id='alerting-tools'></a>

## 告警管理工具

### 相关页面

相关主题：[查询执行工具](#query-tools), [仪表板工具](#dashboard-tools)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [tools/alerting.go](https://github.com/grafana/mcp-grafana/blob/main/tools/alerting.go)
- [tools/alerting_client.go](https://github.com/grafana/mcp-grafana/blob/main/tools/alerting_client.go)
- [tools/alerting_manage_rules_handlers.go](https://github.com/grafana/mcp-grafana/blob/main/tools/alerting_manage_rules_handlers.go)
- [tools/alerting_routing.go](https://github.com/grafana/mcp-grafana/blob/main/tools/alerting_routing.go)
- [tools/alerting_contact_points.go](https://github.com/grafana/mcp-grafana/blob/main/tools/alerting_contact_points.go)
</details>

# 告警管理工具

## 概述

告警管理工具是 mcp-grafana 项目中用于与 Grafana 告警系统集成的核心模块。该工具集提供了完整的 Grafana 告警生命周期管理能力，包括告警规则的创建、查询、更新、删除，以及告警通知路由和联系人管理等功能。 资料来源：[tools/alerting.go:1-50]()

## 工具架构

告警管理工具采用模块化设计，将不同的告警功能分离到独立的文件中：

| 模块文件 | 功能描述 |
|---------|---------|
| `alerting.go` | 主入口文件，定义 MCP 工具的注册和初始化 |
| `alerting_client.go` | 封装与 Grafana Alerting API 的通信逻辑 |
| `alerting_manage_rules_handlers.go` | 处理告警规则的 CRUD 操作 |
| `alerting_routing.go` | 管理通知策略和路由规则 |
| `alerting_contact_points.go` | 管理告警通知联系人 |

### 架构图

```mermaid
graph TD
    A[MCP Client] --> B[alerting.go 工具注册]
    B --> C[alerting_client.go API客户端]
    C --> D{Grafana Alerting API}
    
    D --> E[告警规则管理]
    E --> F[alerting_manage_rules_handlers.go]
    
    D --> G[通知路由管理]
    G --> H[alerting_routing.go]
    
    D --> I[联系人管理]
    I --> J[alerting_contact_points.go]
    
    F --> K[GET/POST/PUT/DELETE 规则]
    H --> L[路由策略/时间间隔]
    J --> M[Email/Slack/Webhook等]
```

## 告警规则管理

### 核心工具功能

`alerting_manage_rules` 是告警管理的核心工具，支持对 Grafana 告警规则的全生命周期管理。 资料来源：[tools/alerting_manage_rules_handlers.go:1-100]()

### 支持的操作类型

| 操作 | 描述 | HTTP 方法 |
|-----|------|----------|
| `list` | 列出所有告警规则 | GET |
| `get` | 获取指定规则详情 | GET |
| `create` | 创建新告警规则 | POST |
| `update` | 更新现有规则 | PUT |
| `delete` | 删除告警规则 | DELETE |
| `set_state` | 修改规则状态 | PUT |

### 参数处理

告警规则工具需要处理 LLM 常见类型不匹配问题，例如字符串与数字类型的转换。在 v0.13.0 版本中修复了此类问题，确保工具调用不会因类型错误而失败。 资料来源：[tools/alerting_manage_rules_handlers.go:80-120]()

## 告警路由管理

### 通知策略

`alerting_manage_routing` 工具提供统一的界面来管理 Grafana 告警的通知策略。该工具在 v0.11.3 版本中引入，将多个相关操作整合到单一工具中。 资料来源：[tools/alerting_routing.go:1-80]()

### 路由配置

```mermaid
graph LR
    A[告警触发] --> B{路由规则匹配}
    B -->|匹配| C[通知策略1]
    B -->|不匹配| D[默认策略]
    C --> E[时间间隔检查]
    D --> E
    E -->|在工作时间内| F[工作时间联系人]
    E -->|非工作时间| G[非工作时间联系人]
```

### 支持的管理对象

| 对象类型 | 功能 |
|---------|------|
| `policies` | 通知策略配置 |
| `contact-points` | 通知联系人点 |
| `time-intervals` | 时间间隔定义 |

## 联系人管理

### 通知类型支持

`alerting_contact_points` 模块负责管理告警通知的接收端点。Grafana 支持多种通知渠道，MCP 工具封装了这些渠道的配置接口。 资料来源：[tools/alerting_contact_points.go:1-60]()

### 常用通知渠道

| 渠道类型 | 说明 |
|---------|------|
| `email` | 电子邮件通知 |
| `slack` | Slack 集成 |
| `webhook` | Webhook 回调 |
| `pagerduty` | PagerDuty 集成 |
| `opsgenie` | OpsGenie 集成 |

## API 客户端封装

### 请求上下文传播

`alerting_client.go` 封装了与 Grafana Alerting API 的通信逻辑。关键设计点之一是确保请求上下文在整个 OpenAPI 调用链中正确传播，避免上下文丢失导致的问题。 资料来源：[tools/alerting_client.go:1-80]()

### 上下文管理

在 v0.13.1 版本中，修复了请求上下文在 OpenAPI 便捷调用中的传播问题，确保所有 API 请求都能正确携带上下文信息。 资料来源：[tools/alerting_client.go:50-100]()

## 使用示例

### 列出告警规则

```json
{
  "name": "alerting_manage_rules",
  "arguments": {
    "operation": "list",
    "folder_uid": "default"
  }
}
```

### 创建告警规则

```json
{
  "name": "alerting_manage_rules",
  "arguments": {
    "operation": "create",
    "rule": {
      "title": "High CPU Usage",
      "condition": "C",
      "data": [...]
    }
  }
}
```

### 管理通知路由

```json
{
  "name": "alerting_manage_routing",
  "arguments": {
    "operation": "get",
    "type": "policies"
  }
}
```

## 版本历史

| 版本 | 变更说明 |
|-----|---------|
| v0.13.0 | 修复 `alerting_manage_rules` 中 LLM 类型不匹配问题 |
| v0.13.1 | 修复请求上下文在 OpenAPI 调用中的传播 |
| v0.11.3 | 新增 `alerting_manage_routing` 统一管理工具 |

## 最佳实践

### 1. 类型安全

在定义告警规则条件时，确保数值类型与 Grafana API 期望的类型一致。工具内部会进行基本类型转换，但建议在源头发起正确的类型。 资料来源：[tools/alerting_manage_rules_handlers.go:100-150]()

### 2. 上下文管理

使用 MCP 工具时，确保在单个请求周期内完成告警操作，避免跨请求的上下文丢失。

### 3. 错误处理

告警 API 调用可能因权限、网络或配置问题失败。建议实现重试机制和详细的错误日志记录。

## 限制与已知问题

- 告警规则的细粒度权限控制依赖于 Grafana 端的 RBAC 配置
- 某些高级告警功能（如告警状态历史）可能需要额外的 API 端点支持
- 社区反馈：多组织环境下的告警管理需要在调用时指定正确的 `orgId`

---

<a id='troubleshooting'></a>

## 故障排除与常见问题

### 相关页面

相关主题：[认证与授权](#authentication), [部署与运维](#deployment)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docs/troubleshooting.md](https://github.com/grafana/mcp-grafana/blob/main/docs/troubleshooting.md)
- [docs/sources/troubleshooting/grafana-version-compatibility.md](https://github.com/grafana/mcp-grafana/blob/main/docs/sources/troubleshooting/grafana-version-compatibility.md)
- [validate_url.go](https://github.com/grafana/mcp-grafana/blob/main/validate_url.go)
- [observability/logs.go](https://github.com/grafana/mcp-grafana/blob/main/observability/logs.go)
- [internal/linter/jsonschema/README.md](https://github.com/grafana/mcp-grafana/blob/main/internal/linter/jsonschema/README.md)
</details>

# 故障排除与常见问题

本文档为 Grafana MCP Server 用户提供常见问题的诊断与解决方案。MCP Server 作为 Grafana 与 AI 助手之间的桥梁，在实际使用中可能遇到认证、查询、多组织支持等问题。以下内容涵盖问题分类、诊断方法及具体解决方案。

## 认证与授权问题

### Service Account Token 认证失败

MCP Server 目前仅支持 Service Account Token 和 Basic Authentication 两种认证方式。当使用 Service Account Token 时，需要确保：

| 配置项 | 说明 | 必需 |
|--------|------|------|
| `GRAFANA_TOKEN` | Service Account 的访问令牌 | 是 |
| `GRAFANA_URL` | Grafana 实例地址 | 是 |
| `GRAFANA_AUTH` | 兼容旧版的基础认证格式 | 否 |

**常见错误：**

```
Error: Unauthorized - Invalid or expired token
```

**解决方案：**

1. 验证 Service Account 权限：确保账户具有访问目标资源的权限
2. 检查 Token 有效期：部分 Token 可能有过期时间限制
3. 确认组织 ID：`orgId` 参数与 Token 所属组织一致

此问题与社区 Issue #284 和 #151 中用户反馈的"普通用户工作流程"问题相关。许多组织使用 SSO 登录，禁用基础认证后无法使用 MCP Server。

### 多组织环境下的 orgId 丢失

在多组织 Grafana 环境中，`get_panel_image` 工具不支持传入 `orgId` 参数，导致面板渲染回退到默认组织。此问题在 Issue #883 中有详细描述。

**影响范围：**

- 面板图像渲染
- 跨组织资源访问
- 权限继承异常

## 查询与数据源问题

### Loki 日志查询结果过大

使用 `query_loki_logs` 查询大量日志时，返回的 JSON 可能超出 LLM 的输出处理预算。Issue #761 请求添加分页/分块功能。

**临时解决方案：**

使用更精确的 LogQL 过滤器缩小查询范围：

```logql
{namespace="prod"} |= "<encounterId>" |= "error"
```

**建议的时间范围限制：**

```logql
{service="myservice"} | __error__=``
```

### 时间戳格式转换错误

在生成 deeplink 时，ISO 8601 时间戳需要转换为 epoch 毫秒格式。v0.13.0 版本修复了此问题，转换逻辑位于 Grafana URL 生成模块。

**错误的 URL 示例：**

```
/explore?left={"time":"2024-01-01T00:00:00Z"}  // 时间格式错误
```

**正确的 URL 格式：**

```
/explore?left={"time":1704067200000}  // epoch 毫秒
```

资料来源：[docs/troubleshooting.md:1-50](https://github.com/grafana/mcp-grafana/blob/main/docs/troubleshooting.md)

### 类型不匹配导致的工具调用失败

在 `alerting_manage_rules` 工具中，LLM 可能传递字符串而非数字类型的参数。v0.13.0 版本已修复此类型转换问题。

**示例错误：**

```json
{"alertId": "123"}  // 应为 {"alertId": 123}
```

## URL 与链接问题

### DeepLink URL 过长

`generate_deeplink` 工具生成的 Explore URL 包含完整的 panes/queries JSON，导致非平凡的 LogQL/PromQL 查询产生数百字符的 URL。此问题在 Issue #820 中被提出。

**问题根源：**

```mermaid
graph TD
    A[查询请求] --> B[generate_deeplink]
    B --> C[构建 panes JSON]
    C --> D[完整序列化到 left 参数]
    D --> E[URL 编码]
    E --> F[超长 URL]
```

**解决方案：**

使用 Grafana 短链接功能 `/goto/<uid>` 可以生成更简洁的链接。该功能通过 `/api/short-urls` 接口创建，URL 长度显著减少。

### URL 验证机制

项目包含专门的 URL 验证模块，用于确保生成的 Grafana URL 格式正确：

```go
// validate_url.go 包含 URL 格式验证逻辑
```

验证规则：

- 检查协议前缀 (`http://` 或 `https://`)
- 验证域名格式
- 确保路径符合 Grafana URL 规范

资料来源：[validate_url.go:1-30](https://github.com/grafana/mcp-grafana/blob/main/validate_url.go)

## 日志与可观测性

### 日志配置与输出

MCP Server 提供结构化日志功能，通过可选的 `Logger` 字段进行配置。日志级别和输出格式可通过环境变量控制。

```mermaid
graph LR
    A[请求入口] --> B[日志记录器]
    B --> C[Console 输出]
    B --> D[文件输出]
    B --> E[远程日志系统]
```

**环境变量配置：**

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `LOG_LEVEL` | 日志级别 | `info` |
| `LOG_FORMAT` | 输出格式 | `json` |

**结构化日志示例：**

```json
{
  "level": "info",
  "msg": "Request processed",
  "duration_ms": 123,
  "endpoint": "/api/query"
}
```

资料来源：[observability/logs.go:1-60](https://github.com/grafana/mcp-grafana/blob/main/observability/logs.go)

## Dashboard 操作问题

### Patch 模式下的仪表板重复

在更新仪表板时，如果 `id`、`uid`、`version` 字段未正确传递，可能导致意外创建重复仪表板。v0.11.6 版本修复了此问题，确保 Patch 模式保留这些标识字段。

**正确的 Patch 请求：**

```json
{
  "id": 123,
  "uid": "abc123",
  "version": 5,
  "title": "Updated Dashboard",
  "panels": [...]
}
```

## 版本兼容性问题

### Grafana 版本要求

不同版本的 MCP Server 对 Grafana 版本有不同要求。请参考兼容性矩阵：

| MCP Server 版本 | 最低 Grafana 版本 | 推荐版本 |
|-----------------|-------------------|----------|
| v0.15.0 | 9.x | 10.x |
| v0.14.0 | 9.x | 10.x |
| v0.13.x | 9.x | 10.x |
| v0.12.x | 8.x | 9.x |

资料来源：[docs/sources/troubleshooting/grafana-version-compatibility.md:1-40](https://github.com/grafana/mcp-grafana/blob/main/docs/sources/troubleshooting/grafana-version-compatibility.md)

## 开发相关问题

### JSONSchema 描述中的逗号转义

Go struct tags 中使用 `jsonschema` 时，description 字段的逗号需要使用 `\\,` 转义。未转义的逗号会导致描述被静默截断。

**错误示例：**

```go
Field string `jsonschema:"description=错误,示例"`  // 在第一个逗号处截断
```

**正确示例：**

```go
Field string `jsonschema:"description=正确示例\\,完整显示"`
```

**使用 lint 命令检查：**

```shell
make lint-jsonschema
```

**自动修复：**

```shell
make lint-jsonschema-fix
```

资料来源：[internal/linter/jsonschema/README.md:1-50](https://github.com/grafana/mcp-grafana/blob/main/internal/linter/jsonschema/README.md)

### OpenAPI 客户端上下文丢失

项目中存在一个 linter 规则，要求使用带 `WithParams` 后缀的方法，而非不带参数的原始方法。原始方法会丢失请求上下文。

**错误调用：**

```go
client.GetDataSources()  // 丢失 context
```

**正确调用：**

```go
client.GetDataSourcesWithParams(nil)  // 保留 context
```

资料来源：[internal/linter/openapi/testdata/src/testpkg/usage.go:1-25](https://github.com/grafana/mcp-grafana/blob/main/internal/linter/openapi/testdata/src/testpkg/usage.go)

## 诊断流程

当遇到问题时，建议按以下流程进行诊断：

```mermaid
flowchart TD
    A[发现问题] --> B{检查日志}
    B -->|有错误信息| C[查看日志级别]
    B -->|无明显错误| D[验证配置]
    C --> E{是认证错误?}
    D --> F{是查询错误?}
    E -->|是| G[检查 Token 和 orgId]
    E -->|否| F
    F -->|是| H[检查数据源配置]
    F -->|否| I[检查版本兼容性]
    G --> J[问题解决]
    H --> J
    I --> J
```

## 获取帮助

如需更多支持：

- 查看 [GitHub Issues](https://github.com/grafana/mcp-grafana/issues) 中是否有类似问题
- 提交新 Issue 时请包含 MCP Server 版本、Grafana 版本和完整错误日志
- 启用 DEBUG 日志级别获取更详细的诊断信息

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：grafana/mcp-grafana

摘要：发现 13 个潜在踩坑项，其中 6 个为 high/blocking；最高优先级：维护坑 - 来源证据：Insturctions。

## 1. 维护坑 · 来源证据：Insturctions

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Insturctions
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_88b5b9a684e64beda991ee684f1f6daa | https://github.com/grafana/mcp-grafana/issues/908 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 安全/权限坑 · 来源证据：Add tool to create Grafana short URLs (/goto/<uid>) via /api/short-urls

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add tool to create Grafana short URLs (/goto/<uid>) via /api/short-urls
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_9cf63ed3a3854737bbca0bbe18c11907 | https://github.com/grafana/mcp-grafana/issues/820 | 来源类型 github_issue 暴露的待验证使用条件。

## 3. 安全/权限坑 · 来源证据：Feature Request: OAuth/SSO Authentication Support (Okta, Google, etc.)

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature Request: OAuth/SSO Authentication Support (Okta, Google, etc.)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_ec3078db55a742068339d4ce3b6cc13f | https://github.com/grafana/mcp-grafana/issues/284 | 来源类型 github_issue 暴露的待验证使用条件。

## 4. 安全/权限坑 · 来源证据：Feature request: pagination / chunking for query_loki_logs results

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature request: pagination / chunking for query_loki_logs results
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_cb6f3653732644d387da810f289708c4 | https://github.com/grafana/mcp-grafana/issues/761 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

## 5. 安全/权限坑 · 来源证据：Security consideration: Prompt injection via dashboard data in MCP context

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security consideration: Prompt injection via dashboard data in MCP context
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_91b6f0b129764ca0b5d8cec3ee1497a7 | https://github.com/grafana/mcp-grafana/issues/680 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

## 6. 安全/权限坑 · 来源证据：`get_panel_image` should support `orgId` when rendering panels

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：`get_panel_image` should support `orgId` when rendering panels
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_a05127eb498a4339b382b65279eef3de | https://github.com/grafana/mcp-grafana/issues/883 | 来源类型 github_issue 暴露的待验证使用条件。

## 7. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:907869862 | https://github.com/grafana/mcp-grafana | README/documentation is current enough for a first validation pass.

## 8. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:907869862 | https://github.com/grafana/mcp-grafana | last_activity_observed missing

## 9. 安全/权限坑 · 下游验证发现风险项

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:907869862 | https://github.com/grafana/mcp-grafana | no_demo; severity=medium

## 10. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:907869862 | https://github.com/grafana/mcp-grafana | no_demo; severity=medium

## 11. 安全/权限坑 · 来源证据：Grafana MCP Server Fails to Discover Datasources

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Grafana MCP Server Fails to Discover Datasources
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_46ffdaae418e420d8fa0ac6ff3b12c7e | https://github.com/grafana/mcp-grafana/issues/398 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 12. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:907869862 | https://github.com/grafana/mcp-grafana | issue_or_pr_quality=unknown

## 13. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:907869862 | https://github.com/grafana/mcp-grafana | release_recency=unknown

<!-- canonical_name: grafana/mcp-grafana; human_manual_source: deepwiki_human_wiki -->