简介

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 工具，涵盖以下功能领域：

资料来源：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 发布说明

认证机制

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

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

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

资料来源：v0.11.5 发布说明

架构设计

传输层架构

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

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 描述字段的逗号转义问题。

// 问题代码（逗号会被截断）
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"`

运行检查命令：

make lint-jsonschema

自动修复命令：

make lint-jsonschema-fix

资料来源：internal/linter/jsonschema/README.md

#### OpenAPI Linter

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

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

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

测试文件中的调用不会触发此检查：

func testHelper(c datasources.ClientService) {
    // 测试文件中的调用不会被标记
    c.GetDataSources()
    c.GetDataSourceByUID("myuid")
}

资料来源：internal/linter/openapi/testdata/src/testpkg/usage.go

社区关注的问题

高优先级功能请求

已知限制

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

版本历史

快速开始

环境要求

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

配置方式

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

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

传输模式选择

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

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

相关资源

• 官方文档
• 问题追踪
• 发布页面
• Docker Hub

环境要求

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

安装方式概览

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

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 包管理器。如未安装，可通过以下命令安装：

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

启动服务

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

uvx mcp-grafana

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

配置文件

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

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

使用 Docker 部署

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

基础运行

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

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 配置文件，便于快速启动完整测试环境：

docker-compose up -d

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

Docker 镜像配置

使用 Helm 部署到 Kubernetes

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

添加 Helm 仓库

首先添加 Grafana 官方 Helm 仓库：

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

安装 Chart

使用默认配置安装：

helm install mcp-grafana grafana/mcp-grafana

自定义配置

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

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 MCP 支持多种认证方式。根据社区反馈（Issue #284），当前版本主要支持：

注意：社区请求支持 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 工具

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
• GitHub 问题反馈：Issue #151 - 普通用户工作流程讨论
• 最新版本发布说明：查看 Releases 页面

概述

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

部署方式

Docker 部署

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

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

当前 Docker 镜像仅提供 latest 标签，尚不支持版本化标签。相关社区讨论可参见 Issue #180。

二进制安装

从 GitHub Releases 页面下载对应平台的二进制文件：

# 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_TOKEN 和 GRAFANA_AUTH 至少需要配置其中之一。

命令行参数

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

mcp-grafana [选项]

通用选项

传输协议选项

Grafana 连接选项

详细参数说明参见：configure/command-line-flags.md

传输协议配置

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

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 客户端直接连接：

mcp-grafana --transport stdio

SSE 模式

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

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

SSE 模式下支持转发请求头（如 Cookie、Authorization），可实现 SSO 和 ALB 会话 cookie 认证。资料来源：transports-and-addresses.md

Streamable HTTP 模式

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

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

认证配置

服务账户令牌（推荐）

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

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

export GRAFANA_TOKEN="glsa_xxxxxxxxxxxxx"

注意：创建服务账户通常需要较高的权限。对于普通用户而言，这种方式可能不够便捷。相关讨论参见 Issue #151。

Basic 认证

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

export GRAFANA_AUTH="admin:admin"

OAuth/SSO 支持

当前版本对 OAuth/SSO 的支持有限。社区请求参见 Issue #284，该问题涉及以下场景：

• Okta 集成
• Google OAuth
• Azure AD

v0.11.5 版本增加了对 Cookie 和 Authorization 请求头的转发支持，可在 SSE 和 streamable-http 模式下启用 SSO 认证。资料来源：transports-and-addresses.md

客户端配置示例

Claude Desktop 配置

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

Cursor IDE 配置

{
  "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

配置加载顺序

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

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

日志配置

日志级别

日志格式

支持两种日志格式：

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

v0.12.1 版本增加了可选的 Logger 字段用于结构化日志记录。资料来源：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. 确认防火墙和网络配置

概述

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

认证方式

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

服务账号令牌认证

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

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

export GRAFANA_AUTH_TOKEN="glsa_xxxxxx"

基本认证

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

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

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

SSO 与负载均衡器会话认证

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

多组织支持

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

工作机制

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]

组织上下文配置

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

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

请求头转发机制

支持转发的请求头

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

配置示例

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

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

客户端缓存管理

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

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

缓存键生成

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

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

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

身份委托

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

工作原理

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

适用场景

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

环境变量配置

*：GRAFANA_AUTH_TOKEN 或 GRAFANA_AUTH_USER+GRAFANA_AUTH_PASSWORD 二选一

安全最佳实践

生产环境建议

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

常见问题排查

相关资源

• 配置文档：docs/sources/configure/authentication.md
• 多组织配置：docs/sources/configure/multi-organization-and-headers.md
• GitHub Issue #284：OAuth/SSO 认证功能请求
• GitHub Issue #151：普通用户工作流程讨论

概述

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

本模块的核心职责包括：

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

部署方式

Docker 容器部署

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

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

# 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 入口点配置
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 配置各项参数：

# 基础配置示例
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：

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

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

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

会话管理

水平扩展架构

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

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

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

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

资料来源：session_horizontal_scaling_test.go

会话空闲超时

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

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

配置参考

完整环境变量列表

健康检查端点

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

# 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 提供商

故障排查

常见部署问题

日志调试

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

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

工具概览

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

核心工具列表

仪表板查询工具

get_dashboard

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

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

#### 输入参数

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

get_dashboards

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

#### 输入参数

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

面板查询工具

get_dashboard_panel_queries

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

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

#### 功能特性

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

#### 输入参数

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

渲染工具

get_panel_image

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

#### 输入参数

#### 已知限制

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

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

导航与深度链接工具

generate_deeplink

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

#### 输入参数

#### 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> 格式别名，显著提升可用性。

#### 输入参数

#### 输出格式

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

数据流架构

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

错误处理与边界情况

常见错误场景

类型兼容性

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
• 辅助函数：tools/dashboard_helpers.go
• 渲染实现：tools/rendering.go
• 导航工具：tools/navigation.go
• 社区问题： #820（短 URL 功能）、#883（orgId 支持）

功能概述

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

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

支持的数据源类型

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

核心工具

ds_query - 通用数据源查询

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

#### 功能特点

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

#### 请求参数

datasources - 数据源管理

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

#### 可用操作

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

专用数据源工具

Snowflake 查询工具

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

#### 核心功能

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

#### 宏变量支持

Amazon Athena 查询工具

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

#### 核心功能

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

#### Schema 发现

ClickHouse 查询工具

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

数据流架构

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

查询执行流程

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 指标查询

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

场景二：Loki 日志查询

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

场景三：Snowflake 数据分析

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

配置与最佳实践

数据源配置要求

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

查询优化建议

已知限制

社区反馈的问题

根据 GitHub issues 社区讨论：

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

当前限制

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

版本历史

相关资源

• 源码：tools/datasources.go
• 通用查询：tools/ds_query.go
• Snowflake 工具：tools/snowflake.go
• Athena 工具：tools/athena.go
• ClickHouse 工具：tools/clickhouse.go

概述

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

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

架构设计

查询执行流程

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[返回标准化结果]

核心接口

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

资料来源：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

核心工具定义

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

工具支持以下关键参数：

资料来源：tools/prometheus.go:80-120

VictoriaMetrics 支持

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

Loki 日志查询工具

工具概览

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

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

主要工具

资料来源：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 两种查询语言。

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

工具列表

资料来源：tools/influxdb.go:1-80

社区需求

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

Graphite 查询工具

功能支持

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

资料来源：tools/graphite.go:1-60

特有功能

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

Elasticsearch 查询工具

查询能力

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

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

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

通用参数模式

时间范围参数

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

数据源选择

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

模板变量支持

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

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

资料来源：tools/loki.go:50-70

最佳实践

查询优化

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

错误处理

性能考虑

• 避免全量数据查询，使用时间窗口分批获取
• 复杂查询考虑预聚合或录制规则
• 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/

社区反馈

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

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

概述

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

工具架构

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

架构图

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

支持的操作类型

参数处理

告警规则工具需要处理 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

路由配置

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

支持的管理对象

联系人管理

通知类型支持

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

常用通知渠道

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

使用示例

列出告警规则

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

创建告警规则

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

管理通知路由

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

版本历史

最佳实践

1. 类型安全

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

2. 上下文管理

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

3. 错误处理

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

限制与已知问题

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

认证与授权问题

Service Account Token 认证失败

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

常见错误：

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 过滤器缩小查询范围：

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

建议的时间范围限制：

{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

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

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

示例错误：

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

URL 与链接问题

DeepLink URL 过长

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

问题根源：

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 格式正确：

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

验证规则：

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

资料来源：validate_url.go:1-30

日志与可观测性

日志配置与输出

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

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

环境变量配置：

结构化日志示例：

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

资料来源：observability/logs.go:1-60

Dashboard 操作问题

Patch 模式下的仪表板重复

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

正确的 Patch 请求：

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

版本兼容性问题

Grafana 版本要求

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

资料来源：docs/sources/troubleshooting/grafana-version-compatibility.md:1-40

开发相关问题

JSONSchema 描述中的逗号转义

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

错误示例：

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

正确示例：

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

使用 lint 命令检查：

make lint-jsonschema

自动修复：

make lint-jsonschema-fix

资料来源：internal/linter/jsonschema/README.md:1-50

OpenAPI 客户端上下文丢失

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

错误调用：

client.GetDataSources()  // 丢失 context

正确调用：

client.GetDataSourcesWithParams(nil)  // 保留 context

资料来源：internal/linter/openapi/testdata/src/testpkg/usage.go:1-25

诊断流程

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

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 中是否有类似问题
• 提交新 Issue 时请包含 MCP Server 版本、Grafana 版本和完整错误日志
• 启用 DEBUG 日志级别获取更详细的诊断信息

Pitfall Log / 踩坑日志

项目：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