Grafana MCP server

Grafana MCP 服务

适用于 Grafana 的 模型上下文协议（MCP）服务。

此服务可访问你的 Grafana 实例及其周边生态系统。

快速开始

需要安装 uv。将以下内容添加到 MCP 客户端配置中（例如 Claude Desktop、Cursor）：

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

对于 Grafana Cloud，请将 GRAFANA_URL 替换为你的实例 URL（例如 https://myinstance.grafana.net）。请参阅使用方法，了解 Docker、二进制文件和 Helm 等更多安装选项。

要求

• 完整功能需要 Grafana 9.0 或更高版本。由于缺少 API 端点，某些功能（尤其是与数据源相关的操作）在更早版本中可能无法正常工作。

功能

MCP 服务目前提供以下功能。此列表仅供参考，不代表未来功能的路线图或承诺。

仪表板

• 搜索仪表板： 按标题、文件夹 UID、标签或星标状态查找仪表板
• 按 UID 获取仪表板： 使用唯一标识符获取完整的仪表板详情。传入可选的 version，即可加载已保存的快照，而不是当前仪表板。警告：大型仪表板可能会占用大量上下文窗口空间。
• 列出仪表板版本： 以精简元数据形式列出仪表板的已保存版本（版本号、作者、时间戳、保存消息）
• 获取仪表板摘要： 获取仪表板的精简概览，包括标题、面板数量、面板类型、变量和元数据；无需获取完整 JSON，以减少上下文窗口占用
• 获取仪表板属性： 使用 JSONPath 表达式（例如 $.title、$.panels[*].title）提取仪表板的特定部分，仅获取所需数据，减少上下文窗口占用
• 更新或创建仪表板： 修改现有仪表板或创建新仪表板。警告：需要完整的仪表板 JSON，可能会占用大量上下文窗口空间。
• 补丁式修改仪表板： 对仪表板应用特定更改，无需提供完整 JSON，即可显著减少针对性修改的上下文窗口占用
• 获取面板查询和数据源信息： 获取仪表板中每个面板的标题、查询字符串和数据源信息（包括 UID 和类型，如有）

运行面板查询

注意： 面板查询工具默认处于禁用状态。要启用这些工具，请将 runpanelquery 添加到 --enabled-tools 标志中。

• 运行面板查询： 使用自定义时间范围和变量覆盖值执行仪表板面板的查询。Infinity 面板在查询使用 backend 或 jq-backend 解析器时运行（Google Sheets 查询始终使用这些解析器）；默认的 simple 解析器以及 UQL 和 GROQ 解析器仅在浏览器中运行。使用 kniepdennis-neo4j-datasource 插件的 Neo4j 面板会通过该插件运行其 Cypher 查询，并打开只读会话。

上下文窗口管理

现在，仪表板工具包含多种策略，可有效管理上下文窗口用量（问题 #101）：

• 使用 get_dashboard_summary 查看仪表板概览并规划修改
• 仅需仪表板的特定部分时，使用 get_dashboard_property 配合 JSONPath
• 除非确实需要完整的仪表板 JSON，否则避免使用 get_dashboard_by_uid

数据源

• 列出并获取数据源信息： 查看所有已配置的数据源，并获取每个数据源的详细信息。
  • 支持的数据源类型：Prometheus、Loki、ClickHouse、CloudWatch、Elasticsearch、OpenSearch、Snowflake、Athena。

查询示例

注意： 查询示例工具默认处于禁用状态。如需启用，请将 examples 添加到 --enabled-tools 标志中。

• 获取查询示例： 获取不同数据源类型的示例查询，以了解查询语法。

Prometheus 查询

• 查询 Prometheus： 对 Prometheus 数据源执行 PromQL 查询（支持即时指标查询和范围指标查询）。
• 查询 Prometheus 元数据： 从 Prometheus 数据源获取指标元数据、指标名称、标签名称和标签值。
• 查询直方图百分位数： 使用 histogram_quantile 计算直方图百分位数值（p50、p90、p95、p99）。

Loki 查询

• 查询 Loki 日志和指标： 使用 LogQL 对 Loki 执行日志查询和指标查询。
• 查询 Loki 元数据： 从 Loki 获取标签名称、标签值和流统计信息。
• 查询 Loki 模式： 获取 Loki 检测到的日志模式，以识别常见日志结构和异常。

InfluxDB 查询

注意： InfluxDB 工具默认处于禁用状态。如需启用，请将 influxdb 添加到 --enabled-tools 标志中。

• 查询 InfluxDB： 使用 InfluxQL（v1.x）或 Flux（v2.x）对 InfluxDB 数据源执行查询。方言会根据数据源配置自动推断，也可通过 dialect 参数显式设置。

SQL 数据源查询

注意： SQL 工具默认处于禁用状态。如需启用，请将 sql 添加到 --enabled-tools 标志中。也支持向后兼容的别名 clickhouse、snowflake 和 athena。

统一的 SQL 工具通过一组工具支持 ClickHouse、Snowflake、Athena、MySQL、PostgreSQL 和 MSSQL。查询会通过 Grafana 的数据源插件执行，因此身份验证由数据源配置处理，凭据不会被 MCP 服务获取。

• 列出数据库／架构／目录： 查找 SQL 数据源的组织单元。对于 Athena，省略目录以列出目录，或传入目录以列出数据库。
• 列出表： 列出数据库或架构中的表，并提供元数据（行数、可用时提供大小）。
• 描述表架构： 获取列名称、类型、是否可为空、默认值和注释。
• 查询 SQL： 执行 SQL 查询，支持数据源专用的宏替换（$__timeFilter(col)、$__from/$__to、$__interval、${varname}）、自动限制结果数量以及模板变量。

CloudWatch 查询

注意： CloudWatch 工具默认处于禁用状态。如需启用，请将 cloudwatch 添加到 --enabled-tools 标志中。

• 列出 CloudWatch 命名空间： 查找可用的 AWS CloudWatch 命名空间。
• 列出 CloudWatch 指标： 列出特定命名空间中可用的指标。
• 列出 CloudWatch 维度： 获取用于筛选指标查询的维度。
• 查询 CloudWatch： 执行支持时间范围的 CloudWatch 指标查询。
• 列出 CloudWatch 日志组： 查找日志组，也可按名称前缀筛选。
• 列出 CloudWatch 日志组字段： 查找日志组中可用的字段。
• 查询 CloudWatch Logs： 对一个或多个日志组运行 CloudWatch Logs Insights 查询。

Google Cloud Logging 查询

注意： Google Cloud Logging 工具默认处于禁用状态。如需启用，请将 cloudlogging 添加到 --enabled-tools 标志中。需要 Google Cloud Logging 数据源插件（googlecloud-logging-datasource）1.8.0 或更高版本，且需要 Grafana 11.2+。较旧的插件版本会返回不同的响应布局，query_cloud_logging 会报错并提示升级。

• 列出 Cloud Logging 项目： 发现此数据源可读取日志的 GCP 项目 ID。
• 列出 Cloud Logging 存储桶和视图： 发现日志存储桶和日志视图，以限定查询范围。
• 查询 Cloud Logging： 使用 Cloud Logging 查询语言筛选条件（例如 resource.type="k8s_container" AND severity>=ERROR），并指定时间范围和限制；返回按时间从新到旧排列的条目，其中包含严重性、正文、标签和跟踪 ID。GCP 身份验证由数据源配置处理。

Graphite 查询

注意： Graphite 工具默认处于禁用状态。如需启用，请将 graphite 添加到 --enabled-tools 标志中。

• 查询 Graphite： 对 Graphite 数据源执行 Graphite render API 查询。
• 列出 Graphite 指标： 浏览和发现 Graphite 指标路径。
• 列出 Graphite 标签： 列出可用的 Graphite 标签及标签值。
• 查询 Graphite 密度： 查询给定模式的 Graphite 指标密度。

Elasticsearch/OpenSearch 查询

注意： Elasticsearch/OpenSearch 工具默认处于禁用状态。如需启用，请将 elasticsearch 添加到 --enabled-tools 标志中。

• 查询 Elasticsearch/OpenSearch： 使用 Lucene 查询语法或 Elasticsearch Query DSL，对 Elasticsearch 或 OpenSearch 数据源执行搜索查询。支持按时间范围筛选，并检索日志、指标或任何已索引的数据。返回的文档包含其索引、ID、源字段和可选的相关性得分。

Quickwit 查询

注意： Quickwit 工具默认处于禁用状态。如需启用，请将 quickwit 添加到 --enabled-tools 标志中。

• 查询 Quickwit： 使用 Lucene 查询语法或部分兼容 Elasticsearch 的 Query DSL，对 Quickwit 数据源执行搜索查询。支持按时间范围筛选，并检索日志或其他已索引文档。返回的文档包含其索引、ID、源字段和可选的相关性得分。

Agent 可观测性

注意： Agent 可观测性工具默认处于禁用状态，且仅适用于 Grafana Cloud。要启用这些工具，请将 agento11y 添加到 --enabled-tools 标志中。

• 列出和搜索对话： 列出近期的大模型对话，或在指定时间范围内使用筛选表达式搜索对话（可按模型、提供商、Agent、状态、错误类型、评估结果等筛选）。搜索结果包含错误计数、评分摘要、评估摘要和跟踪 ID。
• 获取对话详情： 获取单个对话及其所有生成内容，包括提示词和输出。
• 获取生成详情和评分： 按 ID 获取单条生成内容及其评估评分（评估器、评分键、值、是否通过、说明）。
• 读取 Agent 目录： 列出发送遥测数据的 Agent，完整获取某个 Agent 版本（完整系统提示词、每个工具的 JSON 架构，以及它运行时使用的模型），查看某个 Agent 的版本历史，并比较各版本的评估评分汇总。有效版本是 sha256: 哈希值，工具变更不会影响该哈希值；对于未报告自身版本的 Agent，哈希值会根据系统提示词计算，因此修改提示词会生成新版本。目录和版本行都包含 token_estimate，获取完整提示词前值得先检查这一项。
• 检查评估器和模板： 查看评分所用的评估器、评估器派生自的模板，以及 LLM 评审型评估器可用的评审提供商和模型。启用写入工具后，还可创建、派生、测试和删除评估器。
• 检查评估规则和防护机制： 查看将评估器应用于生产流量的异步评估规则，以及内联运行并可发出警告或拒绝请求的防护机制（钩子规则）。启用写入工具后，还可创建、更新、预览和删除这些规则。写入操作以及不会持久化的 preview_rule 和 test_evaluator 操作都需要 grafana-agento11y-app.eval:write 权限，该权限由 Agento11y Admin 角色授予。
• 整理已保存的对话和集合： 查看已保存的对话（为对话添加书签，使其拥有稳定的 ID、名称和标签）以及对话集合，包括每个集合的成员数和每条已保存对话行中嵌入的集合信息。启用写入工具后，还可为对话添加书签、创建和编辑集合，以及添加或移除成员。这些写入操作需要相同的 grafana-agento11y-app.eval:write 权限。
• 读取和编辑测试套件： 列出离线实验所用的带版本测试套件，读取某个测试套件的完整版本历史，并分页查看某个版本的测试用例。启用写入工具后，还可创建测试套件、更改其名称或标签、开启草稿版本、发布版本，以及编写或删除测试用例。已发布的版本会被冻结，因此编辑时需要开启新的草稿。这些写入操作需要 grafana-agento11y-app.eval:write 权限。
• 读取离线实验： 列出针对某个测试套件运行的评估，并查看某次评估的总体通过率、成本和令牌总数。可深入查看每个测试用例的报告，了解各项试验、每位评审者给出的说明和试验的制品元数据。启用写入工具后，还可更改实验的名称或标签，以及取消正在运行的实验；这些操作需要 grafana-agento11y-app.eval:write 权限。实验由 SDK 运行器创建，而非由此工具创建。

Grafana Assistant

注意： Assistant 工具默认处于禁用状态，需要在目标 Grafana 实例上安装 Grafana Assistant 插件（grafana-assistant-app）。这些工具也属于写入工具（Assistant 可能会更改堆栈状态），因此设置 --disable-write 时会跳过它们。要启用这些工具，请将 assistant 添加到 --enabled-tools 标志中。

• 向 Assistant 提问： 向 Grafana Assistant 发送自然语言提示词，并等待完整的文本回复。Assistant 可能会使用工具、指标、日志和其他堆栈上下文，因此其能力范围比单独触发一次数据源查询更广。后续调用时传入返回的 contextId，即可继续同一段对话。复杂任务可能需要几分钟；调用会一直阻塞，直到回复完成或请求超时（5 分钟）。

Incidents

• 搜索、创建和更新事件： 管理 Grafana Incident 中的事件，包括搜索、创建、添加活动，以及读取或设置自定义字段。

Alerting

• 列出并获取告警规则信息： 查看 Grafana 中的告警规则及其状态（触发／正常／错误等）。支持 Grafana 管理的规则，以及来自 Prometheus 或 Loki 数据源的由数据源管理的规则。
• 创建和更新告警规则： 创建新的告警规则或修改现有规则。
• 删除告警规则： 按 UID 移除告警规则。
• 管理告警路由： 查看通知策略、联系点和时间间隔。支持 Grafana 管理的联系点，以及来自外部 Alertmanager 数据源（Prometheus Alertmanager、Mimir、Cortex）的接收器。

Grafana OnCall

• 列出和管理排班： 查看和管理 Grafana OnCall 中的值班排班。
• 获取班次详情： 获取特定值班班次的详细信息。
• 获取当前值班用户： 查看某个排班中当前值班的用户。
• 列出团队和用户： 查看所有 OnCall 团队和用户。
• 列出告警组： 根据状态、集成、标签和时间范围等条件，查看和筛选 Grafana OnCall 中的告警组。
• 获取告警组详情： 根据告警组 ID 获取特定告警组的详细信息。

Admin

注意： Admin 工具默认处于禁用状态。要启用这些工具，请将 admin 添加到 --enabled-tools 标志中。

• 列出团队： 查看 Grafana 中配置的所有团队。
• 列出用户： 查看 Grafana 组织中的所有用户。
• 列出所有角色： 列出所有 Grafana 角色，也可选择筛选可委派的角色。
• 获取角色详情： 根据 UID 获取特定 Grafana 角色的详情。
• 列出角色的分配对象： 列出分配了某个角色的所有用户、团队和服务账号。
• 列出用户的角色： 列出分配给一个或多个用户的所有角色。
• 列出团队的角色： 列出分配给一个或多个团队的所有角色。
• 列出资源的权限： 列出为特定资源（仪表板、数据源、文件夹等）定义的所有权限。
• 描述 Grafana 资源： 列出某种资源类型可用的权限和分配能力。

User

• 用户信息： 获取当前 Grafana 身份信息，包括登录名、电子邮件、姓名、是否为 Grafana（服务器）管理员、当前组织，以及凭据可访问的组织（含角色）。可用于发现 多组织 请求中的有效 orgId 值。

导航

• 生成深度链接： 为 Grafana 资源创建准确的深度链接 URL，而不是依赖大模型猜测 URL。
  • 仪表盘链接： 使用仪表盘 UID 生成直接链接（例如，http://localhost:3000/d/dashboard-uid）
  • 面板链接： 创建指向仪表盘中特定面板的链接，并使用 viewPanel 参数（例如，http://localhost:3000/d/dashboard-uid?viewPanel=5）
  • Explore 链接： 生成指向 Grafana Explore 的链接，并预先配置数据源（例如，http://localhost:3000/explore?schemaVersion=1&panes={"a":{"datasource":"prometheus-uid"}}）。低于 10.2 的 Grafana 版本无法识别 panes，因此这些版本会使用旧版 ?left={...} 格式。
  • 时间范围支持： 在链接中添加时间范围参数（from=now-1h&to=now）
  • 自定义参数： 添加其他查询参数，例如仪表盘变量或刷新间隔

注释

• 获取注释： 使用筛选条件查询注释。支持时间范围、仪表盘 UID、标签和匹配模式。
• 创建注释： 在仪表盘或面板上创建新注释。
• 创建 Graphite 注释： 使用 Graphite 格式（what、when、tags、data）创建注释。
• 更新注释： 替换现有注释的所有字段（完整更新）。
• 修补注释： 仅更新注释中的特定字段（部分更新）。
• 删除注释： 按 ID 永久删除注释。
• 获取注释标签： 列出可用的注释标签，并支持可选筛选。

快照

• 列出快照： 列出仪表盘快照，并支持可选的查询和数量限制筛选条件。
• 获取快照： 按快照键获取快照元数据和仪表盘负载。
• 创建快照： 根据完整的仪表盘负载创建仪表盘快照，并支持可选的过期时间和外部快照选项。
• 删除快照： 按快照键删除快照。

渲染

• 获取面板或仪表盘图像： 将 Grafana 仪表盘面板或完整仪表盘渲染为 PNG 图像。返回 Base64 编码的图像数据，可用于报告、警报或演示文稿。面板默认尺寸为 1000×750 CSS 像素，完整仪表盘默认尺寸为 1200×900，二者的缩放比例均为 1。Explore 默认尺寸为 1000×1000，缩放比例为 1。尺寸受图像渲染器视口限制。支持自定义尺寸、时间范围、主题、缩放比例和仪表盘变量。还支持通过可选的 provisioningPreview 参数，渲染尚未应用的配置仓库分支中的仪表盘（例如，git-sync PR 预览）。
  • 注意：需要安装并配置 Grafana Image Renderer 服务。

配置

• 列出配置仓库： 列出为此 Grafana 实例配置的配置仓库（例如，git-sync 源），并返回各仓库的 slug、源 URL、分支、路径、同步状态和运行状况。
• 验证配置文件： 对指定分支或提交中的配置仓库文件执行试运行应用。返回文件是否会被接受、资源操作（创建/更新）、目标资源类型，以及任何结构化验证错误——与 Grafana PR 评论器使用的准入检查机制相同。

工具列表可配置，因此你可以选择要向 MCP 客户端提供哪些工具。 如果你不使用某些功能，或不想占用太多上下文窗口，这会很有用。 若要禁用某一类工具，请在启动服务时使用 --disable-<category> 标志。例如，若要禁用 OnCall 工具，请使用 --disable-oncall；若要禁用导航深度链接生成，请使用 --disable-navigation。

RBAC 权限

每个工具都需要特定的 RBAC 权限才能正常运行。为 MCP 服务创建服务账号时，请根据计划使用的工具，确保该账号拥有必要的权限。列出的权限是最低限度的必需操作；根据具体用例，您可能还需要授予适当的范围（例如，datasources:*、dashboards:*、folders:*）。

提示：如果您不熟悉 Grafana RBAC，或者想要更快、更简单地完成设置，而不必配置许多细粒度的范围，可以为服务账号分配内置角色，例如 Editor。Editor 角色授予广泛的读写权限，可满足大多数 MCP 服务操作的需求；与手动应用范围相比，它的粒度较粗（因此限制也更少），所以只有在便利性比严格遵循最小权限原则更重要时才使用它。

注意： OnCall 和其他由插件支持的工具通过插件操作进行授权，例如 grafana-irm-app.schedules:read。基本的 Viewer 角色包含读取操作，Editor 则包含写入操作。事件工具只需要 plugins.app:access；IRM 会根据基本角色授权事件操作。

dashboard.grafana.app/dashboards:get 这类 group/resource:verb 格式的操作仅适用于代表用户访问的令牌。服务账号只需要授予其他列出的操作。

如需了解更多关于 Grafana RBAC 的信息，请参阅官方文档。

RBAC 范围

范围定义权限适用的具体资源。每项操作都需要相应的权限与范围组合。

常见范围模式：

• 广泛访问： 使用 * 通配符，授予整个组织范围内的访问权限

  • datasources:* - 访问所有数据源
  • dashboards:* - 访问所有仪表板
  • folders:* - 访问所有文件夹
  • teams:* - 访问所有团队

• 有限访问： 使用特定的 UID 或 ID，将访问权限限制在单个资源

  • datasources:uid:prometheus-uid - 仅访问特定的 Prometheus 数据源
  • dashboards:uid:abc123 - 仅访问 UID 为 abc123 的仪表板
  • folders:uid:xyz789 - 仅访问 UID 为 xyz789 的文件夹
  • teams:id:5 - 仅访问 ID 为 5 的团队
  • global.users:id:123 - 仅访问 ID 为 123 的用户

示例：

• 完整的 MCP 服务访问权限： 为所有工具授予广泛权限

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

• 有限的数据源访问权限： 仅查询特定的 Prometheus 和 Loki 实例

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

• 特定仪表板访问权限： 仅读取特定仪表板

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

工具

工具	类别	描述	所需 RBAC 权限	所需范围
list_teams	管理员*	列出所有团队	teams:read	teams:* or teams:id:1
list_users_by_org	管理员*	列出组织中的用户，支持搜索和分页	org.users:read	global.users:* or global.users:id:123
list_all_roles	管理员*	列出所有 Grafana 角色	roles:read	roles:*
get_role_details	管理员*	获取 Grafana 角色的详细信息	roles:read	roles:uid:editor
get_role_assignments	管理员*	列出角色的分配情况	roles:read, teams.roles:read, users.roles:read	roles:uid:editor
list_user_roles	管理员*	列出用户的角色	users.roles:read	global.users:id:123
list_team_roles	管理员*	列出团队的角色	teams.roles:read	teams:id:7
get_resource_permissions	管理员*	列出资源的权限	dashboards.permissions:read, datasources.permissions:read, folders.permissions:read, serviceaccounts.permissions:read, teams.permissions:read, users.permissions:read	dashboards:uid:abcd1234
get_resource_description	管理员*	描述 Grafana 资源类型	dashboards.permissions:read, datasources.permissions:read, folders.permissions:read, serviceaccounts.permissions:read, teams.permissions:read, users.permissions:read	dashboards:*
user_info	用户	当前身份、功能和可访问的组织	无	—
search_dashboards	搜索	按查询、文件夹 UID、标签或星标状态搜索仪表板	dashboards:read, folders:read	dashboards:* or dashboards:uid:abc123
search_folders	搜索	按标题搜索文件夹	folders:read	folders:* or folders:uid:xyz789
get_dashboard_by_uid	仪表板	按 UID 获取仪表板，也可选择获取已保存的版本	dashboard.grafana.app/dashboards:get, dashboards:read, dashboards:write	dashboards:uid:abc123
list_dashboard_versions	仪表板	列出仪表板的已保存版本（版本、作者、时间、消息）	dashboards:read, dashboards:write	dashboards:uid:abc123
update_dashboard	仪表板	更新仪表板或创建新仪表板	dashboard.grafana.app/dashboards:create, dashboard.grafana.app/dashboards:get, dashboard.grafana.app/dashboards:update, dashboards:create, dashboards:read, dashboards:write, folders:read	dashboards:*, folders:* or folders:uid:xyz789
get_dashboard_panel_queries	仪表板	从仪表板获取面板标题、查询、数据源 UID 和类型	dashboard.grafana.app/dashboards:get, dashboards:read	dashboards:uid:abc123
run_panel_query	运行面板查询*	执行一个或多个仪表板面板查询	dashboard.grafana.app/dashboards:get, dashboards:read, datasources:query, datasources:read	dashboards:uid:*, datasources:uid:*
get_dashboard_property	仪表板	使用 JSONPath 表达式提取仪表板的特定部分	dashboard.grafana.app/dashboards:get, dashboards:read	dashboards:uid:abc123
get_dashboard_summary	仪表板	获取仪表板的简要摘要，不包含完整 JSON	dashboard.grafana.app/dashboards:get, dashboards:read	dashboards:uid:abc123
create_folder	仪表板	创建文件夹	folders:create, folders:read, folders:write	folders:*
list_datasources	数据源	列出数据源	datasources:read	datasources:*
get_datasource	数据源	按 UID 或名称获取数据源	datasources:read	datasources:uid:prometheus-uid
check_datasources_health	数据源	检查一个或多个数据源的运行状况	datasources:query, datasources:read	datasources:uid:*
create_datasource	数据源	创建数据源	datasources:create, datasources:read	datasources:*
update_datasource	数据源	更新数据源	datasources:read, datasources:write	datasources:* or datasources:uid:abc123
get_query_examples	示例*	获取数据源类型的查询示例	无	datasources:*
query_prometheus	Prometheus	对 Prometheus 数据源执行查询	datasources:query, datasources:read	datasources:uid:prometheus-uid
list_prometheus_metric_metadata	Prometheus	列出指标元数据	datasources:query, datasources:read	datasources:uid:prometheus-uid
list_prometheus_metric_names	Prometheus	列出可用的指标名称	datasources:query, datasources:read	datasources:uid:prometheus-uid
list_prometheus_label_names	Prometheus	列出与选择器匹配的标签名称	datasources:query, datasources:read	datasources:uid:prometheus-uid
list_prometheus_label_values	Prometheus	列出特定标签的值	datasources:query, datasources:read	datasources:uid:prometheus-uid
query_prometheus_histogram	Prometheus	计算直方图百分位值	datasources:query, datasources:read	datasources:uid:prometheus-uid
list_incidents	事件	列出 Grafana Incident 中的事件，可选择包含其自定义字段值	plugins.app:access	N/A
create_incident	事件	在 Grafana Incident 中创建事件，可选择设置自定义字段	plugins.app:access	N/A
add_activity_to_incident	事件	向 Grafana Incident 中的事件添加活动条目	plugins.app:access	N/A
update_incident	事件	更新 Grafana Incident 中的事件（状态、严重级别、标题或自定义字段）	plugins.app:access	N/A
get_incident	事件	按 ID 获取单个事件，包括其自定义字段	plugins.app:access	N/A
list_incident_custom_fields	事件	列出为事件配置的自定义字段及其类型和选项	plugins.app:access	N/A
query_loki_logs	Loki	使用 LogQL 查询和检索日志（日志查询或指标查询）	datasources:query, datasources:read	datasources:uid:loki-uid
list_loki_label_names	Loki	列出日志中所有可用的标签名称	datasources:query, datasources:read	datasources:uid:loki-uid
list_loki_label_values	Loki	列出特定日志标签的值	datasources:query, datasources:read	datasources:uid:loki-uid
query_loki_stats	Loki	获取日志流的统计信息	datasources:query, datasources:read	datasources:uid:loki-uid
query_loki_patterns	Loki	查询检测到的日志模式，以识别常见结构	datasources:query, datasources:read	datasources:uid:loki-uid
analyze_loki_labels	Loki	审查 Loki 标签策略（实时或静态），并可选择诊断查询性能	datasources:query, datasources:read	datasources:uid:loki-uid
suggest_loki_alloy_label_config	配置	生成强制使用已批准标签的 Alloy loki.process 片段	无	N/A
query_influxdb	InfluxDB*	使用 InfluxQL（v1）或 Flux（v2）查询 InfluxDB	datasources:query, datasources:read	datasources:uid:influxdb-uid
list_sql_databases	SQL*	列出 SQL 数据源中的数据库、架构或目录	datasources:query, datasources:read	datasources:uid:*
list_sql_tables	SQL*	列出 SQL 数据源中的表	datasources:query, datasources:read	datasources:uid:*
describe_sql_table	SQL*	获取表的列架构	datasources:query, datasources:read	datasources:uid:*
query_sql	SQL*	执行带宏替换的 SQL 查询	datasources:query, datasources:read	datasources:uid:*
list_cloudwatch_namespaces	CloudWatch*	列出可用的 AWS CloudWatch 命名空间	datasources:query, datasources:read	datasources:uid:*
list_cloudwatch_metrics	CloudWatch*	列出命名空间中的指标	datasources:query, datasources:read	datasources:uid:*
list_cloudwatch_dimensions	CloudWatch*	列出指标的维度	datasources:query, datasources:read	datasources:uid:*
list_cloudwatch_dimension_values	CloudWatch*	列出维度键的值	datasources:query, datasources:read	datasources:uid:*
query_cloudwatch	CloudWatch*	执行 CloudWatch 指标查询	datasources:query, datasources:read	datasources:uid:*
list_cloudwatch_log_groups	CloudWatch*	列出 CloudWatch 日志组	datasources:query, datasources:read	datasources:uid:*
list_cloudwatch_log_group_fields	CloudWatch*	列出日志组中发现的字段	datasources:query, datasources:read	datasources:uid:*
query_cloudwatch_logs	CloudWatch*	执行 CloudWatch Logs Insights 查询	datasources:query, datasources:read	datasources:uid:*
list_cloud_logging_projects	Cloud Logging*	列出 Google Cloud Logging 数据源可读取的 GCP 项目	datasources:query, datasources:read	datasources:uid:*
list_cloud_logging_buckets	Cloud Logging*	列出 GCP 项目中的日志存储桶	datasources:query, datasources:read	datasources:uid:*
list_cloud_logging_views	Cloud Logging*	列出日志存储桶中的日志视图	datasources:query, datasources:read	datasources:uid:*
query_cloud_logging	Cloud Logging*	使用 Cloud Logging 查询语言查询日志	datasources:query, datasources:read	datasources:uid:*
query_elasticsearch	Elasticsearch/OpenSearch*	使用 Lucene 语法或 Query DSL 查询 Elasticsearch 或 OpenSearch	datasources:query, datasources:read	datasources:uid:datasource-uid
query_quickwit	Quickwit*	使用 Lucene 语法或 Query DSL 查询 Quickwit	datasources:query, datasources:read	datasources:uid:quickwit-uid
alerting_rules_read	告警	列出并检查告警规则（列表、获取、版本）	alert.rules.external:read, alert.rules:read, datasources:read, folders:read	folders:* or folders:uid:alerts-folder
alerting_rules_write	告警	创建、更新和删除 Grafana 管理的规则，或明确创建数据源管理的规则	alert.provisioning.provenance:write, alert.rules.external:read, alert.rules.external:write, alert.rules:create, alert.rules:delete, alert.rules:read, alert.rules:write, datasources:read, folders:read	folders:*, or datasources:uid:<uid> for external creation
alerting_manage_routing	告警	管理通知策略、联系点和时间间隔	alert.notifications.external:read, alert.notifications.receivers:read, alert.notifications.routes:read, alert.notifications.time-intervals:read, alert.notifications:read, datasources:query, datasources:read, notifications.alerting.grafana.app/routingtrees:get	Global scope
alerting_routing_write	告警	默认创建 Grafana 管理的联系点，或明确创建外部 Alertmanager 接收器	alert.notifications.external:read, alert.notifications.external:write, alert.notifications.receivers:create, alert.provisioning.provenance:write, datasources:read	Global, or datasources:uid:<uid> for external creation
alerting_silences_read	告警	列出并检查告警静默（列表、获取）	alert.instances:read, alert.silences:read	Global scope
alerting_silences_write	告警	创建、更新和到期告警静默	alert.instances:create, alert.instances:read, alert.instances:write, alert.silences:create, alert.silences:read, alert.silences:write	Global scope
list_oncall_schedules	OnCall	列出 Grafana OnCall 中的排班	grafana-irm-app.schedules:read, plugins.app:access	Plugin-specific scopes
get_oncall_shift	OnCall	获取特定 OnCall 值班的详细信息	grafana-irm-app.schedules:read, plugins.app:access	Plugin-specific scopes
get_current_oncall_users	OnCall	获取特定排班中当前值班的用户	grafana-irm-app.schedules:read, grafana-irm-app.user-settings:read, plugins.app:access	Plugin-specific scopes
list_oncall_teams	OnCall	列出 Grafana OnCall 中的团队	grafana-irm-app.user-settings:read, plugins.app:access	Plugin-specific scopes
list_oncall_users	OnCall	列出 Grafana OnCall 中的用户	grafana-irm-app.user-settings:read, plugins.app:access	Plugin-specific scopes
list_alert_groups	OnCall	列出 Grafana OnCall 中的告警组，支持筛选选项	grafana-irm-app.alert-groups:read, plugins.app:access	Plugin-specific scopes
get_alert_group	OnCall	按 ID 获取 Grafana OnCall 中的特定告警组	grafana-irm-app.alert-groups:read, plugins.app:access	Plugin-specific scopes
update_alert_group	OnCall	确认、取消确认、解决或取消解决告警组	grafana-irm-app.alert-groups:read, grafana-irm-app.alert-groups:write, plugins.app:access	Plugin-specific scopes
list_pyroscope_label_names	Pyroscope	列出与选择器匹配的标签名称	datasources:query, datasources:read	datasources:uid:pyroscope-uid
list_pyroscope_label_values	Pyroscope	列出与选择器匹配的指定标签名称的标签值	datasources:query, datasources:read	datasources:uid:pyroscope-uid
list_pyroscope_profile_types	Pyroscope	列出可用的性能分析类型	datasources:query, datasources:read	datasources:uid:pyroscope-uid
query_pyroscope	Pyroscope	从 Pyroscope 查询性能分析数据、指标或两者	datasources:query, datasources:read	datasources:uid:pyroscope-uid
get_assertions	断言	获取指定实体的断言摘要	plugins.app:access	Plugin-specific scopes
agento11y_manage_conversations	Agent 可观测性*	从 Grafana Agent Observability 列出、搜索和获取大模型对话	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access	N/A
agento11y_manage_generations	Agent 可观测性*	从 Grafana Agent Observability 获取大模型生成详情和评估分数	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access	N/A
agento11y_manage_agents	Agent 可观测性*	读取 Agent 目录：列出 Agent、完整获取某个 Agent 版本、列出版本历史和各版本分数汇总	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access	N/A
agento11y_manage_evaluators	Agent 可观测性*	管理评估器、评估器模板和裁判目录（列出、获取、创建或更新、分叉、测试、删除）	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access; 启用写入时还需要 grafana-agento11y-app.eval:write	N/A
agento11y_manage_eval_rules	Agent 可观测性*	管理评估规则和防护规则（列出、获取、创建、更新、预览、删除）	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access; 启用写入时还需要 grafana-agento11y-app.eval:write	N/A
agento11y_manage_eval_collections	Agent 可观测性*	管理已保存的对话及其所属集合（列出、获取、保存、创建、更新、删除、添加和移除成员）	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access; 启用写入时还需要 grafana-agento11y-app.eval:write	N/A
agento11y_manage_experiments	Agent 可观测性*	读取离线实验、其试验、分数、工件元数据和筛选维度；更新和取消实验	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access; 启用写入时还需要 grafana-agento11y-app.eval:write	N/A
agento11y_manage_test_suites	Agent 可观测性*	管理离线实验所用的测试套件、其版本和测试用例（列出、获取、创建、更新、草拟、发布、创建或更新、删除）	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access; 启用写入时还需要 grafana-agento11y-app.eval:write	N/A
ask_assistant	助手*	向 Grafana Assistant 发送提示词并返回完整文本回复（通过 contextId 支持多轮对话）	grafana-assistant-app.chats:access, plugins.app:access	Plugin-specific scopes
generate_deeplink	导航	为 Grafana 资源生成准确的深层链接 URL	无	N/A
get_annotations	注释	按筛选条件获取注释	annotations:read	annotations:* or annotations:id:123
create_annotation	注释	创建新注释（标准格式或 Graphite 格式）	annotations:create	annotations:*
update_annotation	注释	更新注释的特定字段（部分更新）	annotations:read, annotations:write	annotations:*
delete_annotation	注释	按 ID 删除注释	annotations:delete	annotations:*
get_annotation_tags	注释	列出注释标签，可选择筛选	annotations:read	annotations:*
list_snapshots	快照	列出仪表板快照，可选择按查询和数量限制筛选	snapshots:read	N/A
get_snapshot	快照	按快照键获取快照元数据和仪表板负载	无	N/A
create_snapshot	快照	根据完整的仪表板负载创建仪表板快照	dashboards:read, snapshots:create	dashboards:uid:abc123
delete_snapshot	快照	按快照键删除仪表板快照	dashboards:write, snapshots:delete	dashboards:uid:abc123
get_panel_image	渲染	将已存储的仪表板或面板、配置预览或临时 Explore 视图渲染为 PNG 图像	dashboards:read, datasources:explore, datasources:query, datasources:read, provisioning.repositories:read	dashboards:uid:abc123
list_provisioning_repositories	配置	列出配置仓库（例如 git-sync 源），包括其源 URL、分支、同步状态和运行状况	provisioning.grafana.app/repositories:list, provisioning.repositories:read	N/A
validate_provisioning_file	配置	对配置仓库中的文件执行试运行应用，并报告准入验证错误	dashboard.grafana.app/dashboards:get, dashboards:read, folder.grafana.app/folders:get, folders:read, provisioning.grafana.app/repositories:get, provisioning.repositories:read	N/A
search_docs	文档	搜索 Grafana 文档或列出产品组（省略查询即可列出产品）	无	N/A
get_doc	文档	获取文档页面；设置 outline_only 可获取标题，或设置 section 以限定检索范围	无	N/A
search_tempo_traces	Tempo	使用 TraceQL 搜索跟踪	datasources:query, datasources:read	datasources:uid:tempo-uid
query_tempo_metrics	Tempo	使用 TraceQL 根据跟踪计算指标	datasources:query, datasources:read	datasources:uid:tempo-uid
get_tempo_trace	Tempo	按 ID 获取跟踪	datasources:query, datasources:read	datasources:uid:tempo-uid
diff_tempo_traces	Tempo	比较两个跟踪	datasources:query, datasources:read	datasources:uid:tempo-uid
list_tempo_attribute_names	Tempo	列出跨度和资源属性名称	datasources:query, datasources:read	datasources:uid:tempo-uid
list_tempo_attribute_values	Tempo	列出跟踪属性的值	datasources:query, datasources:read	datasources:uid:tempo-uid
get_tempo_traceql_docs	Tempo	获取 TraceQL 文档	无	N/A
query_graphite	Graphite*	查询 Graphite 指标	datasources:query, datasources:read	datasources:uid:graphite-uid
query_graphite_density	Graphite*	查询 Graphite 指标密度	datasources:query, datasources:read	datasources:uid:graphite-uid
list_graphite_metrics	Graphite*	列出 Graphite 指标	datasources:query, datasources:read	datasources:uid:graphite-uid
list_graphite_tags	Graphite*	列出 Graphite 标签	datasources:query, datasources:read	datasources:uid:graphite-uid
get_plugin	插件	获取已安装的插件	plugins.app:access	N/A
search_plugin_information	插件	搜索 grafana.com 插件目录	无	N/A
install_plugin	插件	安装插件	plugins:install	N/A
grafana_api_request	API	调用 Grafana HTTP API 端点	无	取决于端点
* 默认禁用。将类别添加到 --enabled-tools 以启用。

启用 Tempo 查询工具后，get_tempo_trace 工具会在兼容的 MCP 主机中显示交互式跟踪查看器。其现有文本输出仍可使用。有关设置和库嵌入的信息，请参阅 MCP Apps。

CLI 标志参考

mcp-grafana 二进制文件支持各种命令行标志，用于配置：

传输选项：

• -t, --transport：传输类型（stdio、sse 或 streamable-http）——默认值：stdio
• --address：SSE/streamable-http 服务的主机和端口——默认值：localhost:8000
• --base-path：SSE/streamable-http 服务的基础路径。/healthz 和 /metrics 始终在服务根路径提供，而不在此前缀下——它们是仅供内部探针和采集器使用的端点；不将它们放在应用前缀下，可以更轻松地通过反向代理公开 API，而无需同时公开这些端点
• --endpoint-path：streamable-http 服务的端点路径，追加到 --base-path 后——默认值：/mcp
• --sse-keepalive：向每个 SSE 客户端发送 ping 请求的间隔，避免反向代理和负载均衡器关闭空闲事件流（这会结束会话）。将此值设为低于代理的空闲超时，例如，在 ingress-nginx 的默认 proxy-read-timeout 为 60s 时设为 30s。如果连续 3 次 ping 均未收到响应（每次等待半个间隔），客户端将断开连接。接受 Go 时长字符串，最小值为 1s——默认值：0（禁用）。仅适用于 --transport sse
• --server-name：MCP 握手和 OTel service.name 使用的服务名称——默认值：mcp-grafana。此选项会覆盖环境变量 GRAFANA_MCP_SERVER_NAME
• --instructions-append：追加到初始化时返回给 MCP 客户端的服务说明中的文本，以便每个连接的 Agent 都能看到

说明

使用 SSE 时，每个请求的标头不会传递到工具调用：X-Grafana-Service-Account-Token / X-Grafana-API-Key、X-Grafana-Org-Id 以及 GRAFANA_FORWARD_HEADERS 中列出的标头均不起作用；工具调用会使用服务的环境凭据，且 X-Grafana-URL 覆盖不起作用。如果每个调用方都需要使用自己的 Grafana URL、凭据或组织，请使用 streamable-http。

HTTP 传输安全性（仅适用于 SSE / streamable-http）：

MCP 监听器上的每个路由都会执行 Host/Origin 验证——包括 /sse、/mcp，以及与其共用该监听器的 /healthz / /metrics——因此 DNS 重绑定浏览器无法访问其中任何路由。Stdio 传输不受影响。--healthz-address 和 --metrics-address 会启动单独的监听器，该监听器不受此验证机制保护。

• --allowed-hosts：以逗号分隔的 Host 标头值允许列表。默认为 --address 的环回地址变体（例如 localhost:8000,127.0.0.1:8000,[::1]:8000）。如果解析结果为空（未设置、,、, 等），也会回退到默认值，避免拼写错误悄悄禁用检查。Host 标头不在允许列表中的请求会被拒绝，并返回 403。传入 * 可禁用 Host 验证——仅当受信任的反向代理会验证 Host 时才安全。K8s httpGet 探针和外部 /metrics 抓取需要在此列表中指定主机名、传入 *、使用 tcpSocket 探针，或使用单独的端口（--healthz-address / --metrics-address）。
• --allowed-origins：以逗号分隔的 Origin 标头值允许列表。默认为空——任何携带 Origin 标头的请求都会被拒绝（浏览器始终会在跨源请求中发送该标头，而且不应有浏览器直接调用此服务）。设置明确的列表以允许基于浏览器的客户端，或传入 * 以禁用检查。
• --allow-grafana-url-override：启用 X-Grafana-URL 选择。回退到 GRAFANA_ALLOW_URL_OVERRIDE；默认禁用。未设置允许列表时，调用方可以选择服务可访问的任何 HTTP(S) URL。
• --allowed-grafana-urls：可选的、以逗号分隔的精确 Grafana 基础 URL 允许列表，用于 URL 覆盖。回退到 GRAFANA_ALLOWED_URLS。需要启用 --allow-grafana-url-override；显式设置为空的标志会禁用继承的列表。

调用方身份验证（仅限 SSE / streamable-http）：

可选地要求 MCP 客户端向服务进行身份验证。这与服务用于访问 Grafana 的凭据相互独立。Stdio 不受影响。

• --server-auth-token：调用方必须以 Authorization: Bearer <token> 的形式发送的 Bearer 令牌。回退到 MCP_GRAFANA_SERVER_TOKEN 环境变量。设置后，没有有效令牌的请求会在运行任何工具之前被拒绝，并返回 401。建议使用环境变量，以免机密显示在进程参数中。

仅当设置了 --server-auth-token 时才会强制执行调用方身份验证。未设置该参数且服务绑定到非环回地址时，服务仍会启动，但会记录安全错误——错误以 error 日志级别输出，因此不会被 --log-level 隐藏（环回地址和 stdio 不受影响）；未来的主要版本会将其改为启动错误。在非环回地址上启用调用方身份验证时，请使用 TLS（或 TLS 终止）。启用调用方身份验证后，经过验证的 Authorization 标头会在请求到达 Grafana 前被剥离；启动时会拒绝同时使用 --server-auth-token 和 GRAFANA_FORWARD_HEADERS=Authorization 的配置。

Grafana URL 覆盖（仅限 streamable-http）：

警告

URL 覆盖允许 MCP 调用方选择出站 HTTP(S) 目标。允许列表可以限制 URL，但无法验证调用方身份，也无法将令牌绑定到目标。

请部署在身份验证代理之后，由代理授权每个目标、替换客户端提供的 URL 和令牌标头，并提供相匹配的令牌。将服务的出站网络访问限制为已批准的目标。

未设置允许列表时，伪造的请求令牌可能导致请求被发送到任何可访问的 HTTP(S) 服务，包括内部服务和元数据服务。

设置 GRAFANA_ALLOW_URL_OVERRIDE=true（或 --allow-grafana-url-override）以启用目标选择，从而支持大型集群。若要限制目标，还需设置 GRAFANA_ALLOWED_URLS=https://one.example.com,https://two.example.com/grafana（或 --allowed-grafana-urls）。

在每个选择目标的 MCP 请求中发送以下标头：

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

如果配置了 --server-auth-token，还需发送 Authorization: Bearer <MCP caller token>。这用于向 MCP 服务进行身份验证，与 X-Grafana-Service-Account-Token 不同，后者用于所选 Grafana 实例。你的代理可以为每个实例发送不同的 Grafana 令牌；服务不会在这些实例之间共享同一个已配置令牌。已弃用的 X-Grafana-API-Key 标头也可使用。没有请求 Grafana 令牌时，URL 标头会被拒绝。由于传入请求中包含令牌，请使用 TLS。

允许列表会对完全匹配的基础 URL 进行匹配，包括协议、端口和路径；不支持通配符。Grafana 身份验证并不能防御 SSRF。

对于选定的 URL，服务不会使用 GRAFANA_SERVICE_ACCOUNT_TOKEN、GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE、GRAFANA_API_KEY、环境变量中的基本身份验证、GRAFANA_EXTRA_HEADERS 或客户端证书。即使设置了 --tls-skip-verify，TLS 验证仍会启用；已配置的 CA 文件仍会生效。该请求中明确转发的标头仍会生效。重定向以及选定基础 URL 以外的其他 Grafana API 请求都会被阻止。未包含 X-Grafana-URL 的请求仍按常规使用 GRAFANA_URL 和环境凭据。此选项仅适用于流式 HTTP。它不适用于 SSE，因为 SSE 不会将每个请求的标头传递给工具调用；在那里，选定的 URL 不会附带调用方的令牌，因此调用会失败。

调试和日志记录：

• --debug：启用调试模式，详细记录 HTTP 请求和响应
• --log-level：日志级别（debug、info、warn、error）——默认值：info

Grafana 客户端选项：

• --grafana-timeout：Grafana 客户端请求的时间限制。接受 Go 时长字符串（例如，10s、500ms）——默认值：10s
• --allow-cross-origin-redirects：允许出站 Grafana 客户端跟随重定向到不同的协议、主机或端口。默认值为 false；环境变量回退项为 GRAFANA_ALLOW_CROSS_ORIGIN_REDIRECTS。启用此选项可能会将 Grafana 凭据发送到重定向目标。按请求选定的 Grafana URL 仍会固定到其选定的目标。
• --include-args-in-spans：在 OpenTelemetry spans 中包含工具调用参数。仅在非生产环境中启用，或确保参数不含 PII 时启用——默认值：false

可观测性：

• --metrics：在 /metrics 启用 Prometheus 指标端点
• --metrics-address：指标服务的独立地址（例如，:9090）。若为空，指标将在主服务上提供
• --healthz-address：/healthz 的独立地址（例如，:8080）。若为空，/healthz 将在主服务上提供。当两个地址相同时，与 --metrics-address 共用一个监听器。辅助监听器会跳过 Host/Origin 验证。
• --slow-request-threshold：当任何 MCP 请求（工具调用、列表、资源读取等）耗时超过此时长时，记录一条事件。接受 Go 时长字符串（例如，500ms、5s）。默认值 0 会禁用慢请求日志记录。请参阅慢请求日志记录部分。
• --slow-request-log-level：慢请求事件的日志级别（info 或 warn）——默认值：warn。

匿名使用情况统计：

• --usage-stats：匿名使用情况统计报告：enabled、disabled 或 log（将待发送的报告打印到 stderr，不发送任何内容）。此选项会覆盖 GRAFANA_USAGE_STATS 环境变量，而该环境变量会覆盖 DO_NOT_TRACK；任何无法识别的值都会禁用报告。请参阅匿名使用情况统计部分。 工具配置：
• --enabled-tools：以逗号分隔的已启用类别列表，默认启用除 admin、agento11y、assistant、athena、clickhouse、cloudlogging、cloudwatch、elasticsearch、examples、graphite、quickwit、runpanelquery 和 snowflake 以外的所有类别。要启用默认禁用的类别，请将其添加到列表中（例如，"search,datasource,...,snowflake"）
• --max-loki-log-limit：每次 query_loki_logs 调用返回的最大日志行数，默认值：100。注意：此值至少要比 Loki 服务端的 max_entries_limit_per_query 小 1，才能检测到结果是否被截断（该工具会在内部请求 limit+1 条，以检测是否还有更多数据）。
• --loki-guardrail-mode：query_loki_logs 的 Loki 查询成本护栏，默认值：off。对于不带行筛选器的日志查询，Loki 不会强制执行 max_query_bytes_read，因此，时间范围较大的宽泛选择器可能会扫描数 TB 数据；该护栏要求使用具有选择性的流选择器，限制有效时间范围（包括 [30d] 这样的范围向量时长），并在运行查询前检查 Loki 的索引／统计信息字节估算值。shadow 会记录本应被拦截的查询，但仍允许其运行（仍需进行索引／统计信息往返请求）；enforce 会拒绝这类查询，并提供 LLM 可据此改写查询的建议。在 VictoriaLogs 上，该护栏仅适用于选择器形态（{...}）的查询——如果无法解析出选择器（常见的不带花括号的 LogsQL 形式），查询会完全直接通过，且不会进行字节预算检查（因为没有低成本的索引估算）。环境变量回退：GRAFANA_LOKI_GUARDRAIL_MODE。
• --loki-guardrail-max-bytes：单次 query_loki_logs 调用可扫描的最大字节数，通过 Loki 的索引／统计信息 API 进行估算，默认值：107374182400（100 GiB）。0 表示禁用字节预算检查。环境变量回退：GRAFANA_LOKI_GUARDRAIL_MAX_BYTES。
• --loki-guardrail-max-range：单次 query_loki_logs 调用的最大有效时间范围，包括范围向量时长，默认值：24h。接受 Go 时长字符串。0 表示禁用时间范围检查。环境变量回退：GRAFANA_LOKI_GUARDRAIL_MAX_RANGE。
• --loki-enforced-matchers：添加到每个原生 Loki 查询中的 LogQL 标签匹配器（以 AND 连接），用于限制可读取的日志流（例如，environment=~"prod|staging"）。需要设置 --disable-api。参见 Loki 查询强制规则。
• --loki-label-enumeration-fallback：当负向强制匹配器无法限定标签枚举工具的范围时，这些工具的处理方式：reject（默认）或 unfiltered。参见 Loki 查询强制规则。
• --disable-search：禁用搜索工具
• --disable-datasource：禁用数据源工具
• --disable-incident：禁用事件工具
• --disable-prometheus：禁用 prometheus 工具
• --disable-write：禁用写入工具（创建／更新操作）
• --disable-query：禁用查询工具（用于对数据源执行查询的工具）；元数据和发现工具仍可用
• --enable-query：即使启用了 --disable-write，也保留原始 SQL 查询工具（query_sql、query_influxdb）的注册状态。等同于 --enable-write-tools=query_sql,query_influxdb；这是该常见用例的简写。
• --enable-write-tools：以逗号分隔的单个工具名称列表；即使启用了 --disable-write，也保留这些工具的注册状态，适用于写入行为范围足够明确、可单独重新启用的工具。如果某个工具所属的整个类别已禁用，此选项不会生效。例如，--enable-write-tools=generate_deeplink 可让 URL 缩短功能（shorten=true）在启用 --disable-write 时仍可用。
• --disable-loki：禁用 loki 工具
• --disable-elasticsearch：禁用 elasticsearch 和 opensearch 工具
• --disable-quickwit：禁用 quickwit 工具
• --disable-influxdb：禁用 InfluxDB 工具
• --disable-alerting：禁用告警工具
• --disable-dashboard：禁用仪表板工具
• --disable-oncall：禁用 oncall 工具
• --disable-asserts：禁用 asserts 工具
• --disable-admin：禁用管理工具
• --disable-pyroscope：禁用 pyroscope 工具
• --disable-navigation：禁用导航工具
• --disable-rendering：禁用渲染工具（面板／仪表板图像导出）
• --disable-snapshot：禁用快照工具
• --disable-cloudwatch：禁用 CloudWatch 工具
• --disable-cloudlogging：禁用 Google Cloud Logging 工具
• --disable-examples：禁用查询示例工具
• --disable-sql：禁用 SQL 数据源工具（ClickHouse、Snowflake、Athena、MySQL、PostgreSQL、MSSQL）。别名 --disable-clickhouse、--disable-snowflake、--disable-athena 也可用。
• --disable-runpanelquery：禁用运行面板查询工具
• --disable-graphite：禁用 Graphite 工具
• --disable-provisioning：禁用配置管理工具
• --disable-agento11y：禁用 Agent 可观测性工具
• --disable-assistant：禁用 Grafana 助手工具
• --disable-docs：禁用文档工具

只读模式

--disable-write 标志可让 MCP 服务以只读模式运行，防止对 Grafana 实例执行任何写入操作。适用于需要提供安全只读访问权限的场景，例如：

• 使用权限有限的只读服务账户
• 向 AI 助手提供可观测性数据，但不允许其进行修改
• 在需要限制写入权限的生产环境中运行
• 在测试和开发场景中防止意外修改

启用 --disable-write 后，将禁用以下写入操作：

仪表板工具：

• update_dashboard

文件夹工具：

• create_folder

事件工具：

• create_incident
• add_activity_to_incident
• update_incident

告警工具：

• alerting_rules_write（创建、更新、删除操作）
• alerting_silences_write（创建、更新、删除操作）
• alerting_routing_write（create_contact_point 操作）

OnCall 工具：

• update_alert_group

注释工具：

• create_annotation
• update_annotation
• delete_annotation

快照工具：

• create_snapshot
• delete_snapshot

导航工具：

• generate_deeplink（忽略 shorten=true，并返回完整 URL；传入 --enable-write-tools=generate_deeplink 可保留 URL 缩短功能）

原始 SQL 查询工具：

这些工具会直接执行你提供的任何查询，而不会检查查询内容，因此，只要数据源凭据允许，它们就可能执行写入操作：query_sql 会运行 DROP TABLE，query_influxdb 会运行 DELETE。因此，只读模式会移除这些工具。如果已知数据源凭据为只读，可传入 --enable-query 保留这些工具。

• query_sql
• query_influxdb

Agent 可观测性工具：

• agento11y_manage_evaluators（upsert、删除、分叉、测试评估器操作）
• agento11y_manage_eval_rules（创建、更新、删除、预览规则和防护措施操作）
• agento11y_manage_eval_collections（保存和删除已保存的对话；创建、更新、删除集合；添加和移除集合成员）
• agento11y_manage_experiments（更新和取消实验操作）
• agento11y_manage_test_suites（创建和更新测试套件；创建和发布版本；upsert 和删除测试用例）

所有读取操作仍可使用，你可以查询仪表板、运行 PromQL/LogQL 查询、列出资源并检索数据。无法表达写入操作的查询语言——PromQL、LogQL、TraceQL、Elasticsearch DSL、Graphite、CloudWatch——仍可在只读模式下使用其查询工具；只有上面列出的原始 SQL 查询工具会被移除。

无查询模式

--disable-query 标志会移除所有会对数据源执行查询的工具，同时保留元数据和发现工具。如果你希望助手能够探索现有内容——数据源、仪表板、指标名称、标签、表结构——但不执行可能成本高昂或暴露数据的查询，这个选项就很有用。例如，服务账号拥有 datasources:read 权限，但没有 datasources:query 权限。

这是三种查询设置中限制最严格的一种，并且优先于 --enable-query：

标志	安全查询工具（query_prometheus、query_loki_logs、run_panel_query 等）	原始 SQL 查询工具（query_sql、query_influxdb）
(无)	已注册	已注册
--disable-write	已注册	未注册
--disable-write --enable-query	已注册	已注册
--disable-query	未注册	未注册
--disable-query --enable-query	未注册	未注册

启用 --disable-query 后，以下工具不会注册：

Prometheus 工具：

• query_prometheus
• query_prometheus_histogram

Loki 工具：

• query_loki_logs
• query_loki_patterns

query_loki_stats 和 analyze_loki_labels 仍会注册：两者都会向数据源发送选择器，但读取的是索引，并返回流、数据块和字节数，而非日志内容。

Elasticsearch/OpenSearch 和 Quickwit 工具：

• query_elasticsearch
• query_quickwit

InfluxDB 工具（也会被 --disable-write 移除，见上文）：

• query_influxdb

SQL 数据源工具（也会被 --disable-write 移除，见上文）：

• query_sql

Graphite 工具：

• query_graphite
• query_graphite_density

CloudWatch 工具：

• query_cloudwatch
• query_cloudwatch_logs

Google Cloud Logging 工具：

• query_cloud_logging

Pyroscope 工具：

• query_pyroscope

运行面板查询工具：

• run_panel_query

elasticsearch、quickwit、influxdb 和 runpanelquery 类别中没有其他工具，因此禁用查询时，这些类别不会注册任何工具。其他每个类别中的同类工具——list_prometheus_metric_names、list_loki_label_values、describe_sql_table、list_cloudwatch_metrics、list_cloud_logging_projects 等——仍可使用。

请注意，--disable-query 会限制查询工具以及 grafana_api_request 中对 /api/ds/query 的 POST 请求路径，但不会限制指向数据源的所有路由。在只读模式下，只有启用查询工具时，grafana_api_request 才允许向 /api/ds/query 发送 POST 请求（与原始 SQL 工具采用相同的限制：除非 --enable-query 覆盖，否则会被 --disable-write 禁止）。用于在服务端渲染面板的 get_panel_image 不受影响。

客户端 TLS 配置（用于 Grafana 连接）：

• --tls-cert-file：用于客户端身份验证的 TLS 证书文件路径
• --tls-key-file：用于客户端身份验证的 TLS 私钥文件路径
• --tls-ca-file：用于服务器验证的 TLS CA 证书文件路径
• --tls-skip-verify：跳过 TLS 证书验证（不安全）

服务端 TLS 配置（仅适用于 streamable-http 传输）：

• --server.tls-cert-file：用于服务器 HTTPS 的 TLS 证书文件路径
• --server.tls-key-file：用于服务器 HTTPS 的 TLS 私钥文件路径

用法

此 MCP 服务既适用于本地 Grafana 实例，也适用于 Grafana Cloud。对于 Grafana Cloud，请在下方的配置示例中使用实例 URL（例如 https://myinstance.grafana.net），替代 http://localhost:3000。

1. 如果使用服务账号令牌进行身份验证，请在 Grafana 中创建一个具有足够权限、能够使用所需工具的服务账号， 生成服务账号令牌，并将其复制到剪贴板，以便在配置文件中使用。 有关如何创建服务账号令牌的详情，请参阅 Grafana 服务账号文档。 提示：如果你不熟悉如何配置精细的 RBAC 作用域，较简单（但限制较少）的做法是为服务账号分配内置的 Editor 角色。这会授予广泛的读写权限，足以满足大多数 MCP 服务操作的需求——当便利性比严格遵循最小权限原则更重要时，可采用此做法。

   注意： 环境变量 GRAFANA_API_KEY 已弃用，并将在未来版本中移除。请改用 GRAFANA_SERVICE_ACCOUNT_TOKEN。为保证向后兼容，旧变量名仍会继续生效，但会显示弃用警告。

从文件读取服务账号令牌

你可以将 GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE 指向包含令牌的文件路径，而不必通过 GRAFANA_SERVICE_ACCOUNT_TOKEN 内联传入令牌。每次请求都会重新读取该文件，因此轮换后的令牌会自动生效，无需重启服务。

这在 Kubernetes 中尤其有用：作为卷挂载的 Secret 在底层 Secret 更改时会就地更新（通常在约 1 分钟内）。结合按请求缓存客户端（缓存键为令牌值），轮换后的令牌会透明地创建新客户端，无需重启 Pod，也不会造成停机：

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

文件内容开头和结尾的空白（包括末尾换行符）都会被移除。如果同时设置了 GRAFANA_SERVICE_ACCOUNT_TOKEN 和 GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE，则以内联令牌为准。

多组织支持

你可以通过以下任一方式指定要与之交互的组织：

• 环境变量： 将 GRAFANA_ORG_ID 设置为组织的数字 ID
• HTTP 标头： 使用可流式 HTTP 传输时设置 X-Grafana-Org-Id（标头优先于环境变量——这意味着你也可以设置默认组织）。

提供组织 ID 后，MCP 服务会在所有发往 Grafana 的请求中设置 X-Grafana-Org-Id 标头，确保操作在指定组织的上下文中执行。

动态（每次调用）选择组织

以上选项会将组织固定为整个连接使用的组织。若要让单个连接在每次工具调用时针对不同组织，请使用 --dynamic-multi-org 标志启动服务。默认情况下，此功能处于关闭状态。

启用后，每个工具都会接受一个可选的 orgId 参数，用于覆盖该次调用所使用的连接组织（同时决定 X-Grafana-Org-Id 标头，以及 app-platform API 所解析出的 Kubernetes 命名空间）。代理的数据源工具还会跨凭据可访问的所有组织进行发现。省略 orgId 的调用会使用连接的默认组织。

此功能仅适用于属于多个组织的凭据（例如用户身份或代表用户的身份）；服务账号令牌仍绑定到单个组织。使用 user_info 工具可查看哪些 orgId 值有效。

组织 ID 示例：

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

自定义 HTTP 标头

你可以使用 GRAFANA_EXTRA_HEADERS 环境变量，为所有 Grafana API 请求添加任意 HTTP 标头。其值应为将标头名称映射到标头值的 JSON 对象。

自定义标头示例：

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

SOCKS5 代理

你可以通过 GRAFANA_SOCKS5_PROXY 环境变量，将此服务发往 Grafana 的所有请求路由到 SOCKS5 代理。该代理仅作用于此服务发往 Grafana 的流量：它不会修改全局 HTTP_PROXY/HTTPS_PROXY 变量；设置后，也只会覆盖 Grafana 传输的代理选择，不会影响其他 MCP 服务或你的 shell 会话。未设置时，行为保持不变。

URL 必须使用 socks5:// 或 socks5h:// 方案（Go 会将二者视为相同：主机名解析由代理完成），并且可以包含凭据，例如 socks5://user:[email protected]:1080。

示例：

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

代理 URL 无效会导致启动失败；如果运行时无法建立代理连接，服务会安全地拒绝连接，而不会悄悄地直接发送 Grafana 流量。

转发客户端的标头（仅限 Streamable-HTTP）

当 MCP 服务运行在处理 SSO 的网关或反向代理后面时（例如使用 OIDC 的 AWS ALB），必须将每个用户的会话 Cookie 传递给 Grafana，以便它将请求与经过身份验证的用户关联起来。GRAFANA_FORWARD_HEADERS 环境变量通过指定一个以逗号分隔的标头名称允许列表，来启用此功能；这些标头会从传入的 HTTP 请求复制到每个发往 Grafana 的 API 请求中。

此功能仅适用于使用 streamable-http（-t streamable-http）传输的情况。在 stdio 或 SSE 模式下无效。

示例：转发会话 Cookie

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

你可以用逗号分隔多个标头来转发它们：

GRAFANA_FORWARD_HEADERS=Cookie,X-Session-Id

转发的标头会与 GRAFANA_EXTRA_HEADERS 中定义的标头合并。如果某个标头名称同时出现在两者中，该请求将优先使用传入请求中的值。

跟踪上下文标头（traceparent、tracestate、baggage）例外：服务会自行传播跟踪上下文，因此转发的值不会覆盖服务注入的值。请参阅可观测性。

2. 安装 mcp-grafana 有以下几种方式：

   • uvx（推荐）：如果已安装 uv，则无需额外设置 — uvx 会自动下载并运行服务：

     uvx mcp-grafana
     

   • Docker 镜像：使用 Docker Hub 上的预构建 Docker 镜像。

     重要：Docker 镜像的入口点默认配置为以 SSE 模式运行 MCP 服务，但大多数用户需要使用 STDIO 模式，以便直接与 Claude Desktop 等 AI 助手集成：

     1. STDIO 模式：使用 stdio 模式时，必须通过 -t stdio 显式覆盖默认值，并添加 -i 标志以保持 stdin 打开：

     docker pull grafana/mcp-grafana
     # 对于本地 Grafana：
     docker run --rm -i -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> grafana/mcp-grafana -t stdio
     # 对于 Grafana Cloud：
     docker run --rm -i -e GRAFANA_URL=https://myinstance.grafana.net -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> grafana/mcp-grafana -t stdio
     

     注意 — 保护网络模式： 在 SSE 和 streamable-http 模式下，容器会绑定到非回环地址（0.0.0.0:8000）。如果未设置调用方令牌，服务仍会启动，但会记录安全错误（日志级别为 error，因此不会被 --log-level 隐藏；并且未来的主版本将拒绝启动）。设置 MCP_GRAFANA_SERVER_TOKEN，要求客户端提供 Authorization: Bearer <token>（推荐）。STDIO 模式不受影响。请参阅调用方身份验证。

     2. SSE 模式：在此模式下，服务作为 HTTP 服务运行，客户端可以连接到该服务。必须使用 -p 标志公开端口 8000：

     docker pull grafana/mcp-grafana
     docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> -e MCP_GRAFANA_SERVER_TOKEN=<caller auth token> grafana/mcp-grafana
     

     3. Streamable HTTP 模式：在此模式下，服务以独立进程运行，可处理多个客户端连接。必须使用 -p 标志公开端口 8000。此模式下必须使用 -t streamable-http 显式覆盖默认设置。

     docker pull grafana/mcp-grafana
     docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> -e MCP_GRAFANA_SERVER_TOKEN=<caller auth token> grafana/mcp-grafana -t streamable-http
     

     使用服务器 TLS 证书启用 HTTPS Streamable HTTP 模式：

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

   • 下载二进制文件：从发布页面下载最新版本的 mcp-grafana，并将其放入 $PATH。

   • 从源代码构建：如果已安装 Go 工具链，也可以从源代码构建并安装。使用 GOBIN 环境变量 指定二进制文件的安装目录。该目录也应位于 $PATH 中。

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

   • 使用 Helm 部署到 Kubernetes：使用 Grafana helm-charts 仓库中的 Helm chart

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

3. 将服务配置添加到客户端配置文件中。例如，Claude Desktop 的配置：

   使用 uvx 时：

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

   使用二进制文件时：

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

注意：如果在 Claude Desktop 中看到 Error: spawn mcp-grafana ENOENT，需要指定 mcp-grafana 的完整路径。

使用 Docker 时：

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

注意：此处必须使用 -t stdio 参数，因为它会覆盖 Docker 镜像中的默认 SSE 模式。

在 VSCode 中使用远程 MCP 服务

如果你使用 VSCode，并以 SSE 模式运行 MCP 服务（使用 Docker 镜像且未覆盖传输方式时，默认采用此模式），请确保 .vscode/settings.json 包含以下内容：

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

使用服务器 TLS 证书启用 HTTPS Streamable HTTP 模式：

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

调试模式

在命令中添加 -debug 标志，即可为 Grafana 传输启用调试模式。此模式会详细记录 MCP 服务与 Grafana API 之间的 HTTP 请求和响应，有助于排查问题。

要在 Claude Desktop 配置中使用调试模式，请按如下方式更新配置：

使用二进制文件时：

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

使用 Docker 时：

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

注意：与标准配置一样，必须使用 -t stdio 参数来覆盖 Docker 镜像中的默认 SSE 模式。

TLS 配置

如果你的 Grafana 实例位于 mTLS 后面，或需要自定义 TLS 证书，你可以将 MCP 服务配置为使用自定义证书。服务支持以下 TLS 配置选项：

• --tls-cert-file：用于客户端身份验证的 TLS 证书文件路径
• --tls-key-file：用于客户端身份验证的 TLS 私钥文件路径
• --tls-ca-file：用于服务端验证的 TLS CA 证书文件路径
• --tls-skip-verify：跳过 TLS 证书验证（不安全，仅用于测试）

客户端证书身份验证示例：

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

Docker 示例：

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

TLS 配置会应用于 MCP 服务使用的所有 HTTP 客户端，包括：

• 主 Grafana OpenAPI 客户端
• Prometheus 数据源客户端
• Loki 数据源客户端
• 事件管理客户端
• 告警客户端
• Asserts 客户端

直接使用 CLI 的示例：

使用自签名证书进行测试：

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

使用客户端证书身份验证：

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

仅使用自定义 CA 证书：

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

以编程方式使用：

如果你以编程方式使用此库，也可以创建启用了 TLS 的上下文函数：

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

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

URL 验证：

直接调用 NewGrafanaClient（stdio 或以编程方式构建）时，请预先验证 URL，以避免发生可触发的 panic：

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

服务端 TLS 配置（仅适用于 Streamable HTTP 传输）

使用 Streamable HTTP 传输（-t streamable-http）时，你可以将 MCP 服务配置为通过 HTTPS 而非 HTTP 提供服务。当你需要保护 MCP 客户端与服务本身之间的连接时，这会很有用。

Streamable HTTP 传输支持以下 TLS 配置选项：

• --server.tls-cert-file：用于服务端 HTTPS 的 TLS 证书文件路径（启用 TLS 时必需）
• --server.tls-key-file：用于服务端 HTTPS 的 TLS 私钥文件路径（启用 TLS 时必需）

注意：这些标志与上文所述的客户端 TLS 标志完全独立。客户端 TLS 标志用于配置 MCP 服务如何连接到 Grafana，而这些服务端 TLS 标志用于配置客户端在使用 Streamable HTTP 传输时如何连接到 MCP 服务。

HTTPS Streamable HTTP 服务示例：

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

这会在 HTTPS 端口 8443 上启动 MCP 服务。随后，客户端将连接到 https://localhost:8443/，而不是 http://localhost:8000/。

启用服务端 TLS 的 Docker 示例：

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

健康检查端点

使用 SSE（-t sse）或 Streamable HTTP（-t streamable-http）传输时，MCP 服务会在 /healthz 提供健康检查端点。负载均衡器、监控系统或编排平台可以使用此端点验证服务是否正在运行并接受连接。

端点： GET /healthz

响应：

• 状态码：200 OK
• 正文：ok

使用示例：

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

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

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

注意： 健康检查端点仅适用于 SSE 或 Streamable HTTP 传输。stdio 传输（-t stdio）不提供此端点，因为 stdio 不会暴露 HTTP 服务。

匿名使用统计

服务器可以向 Grafana Labs 报告匿名使用统计信息：调用了哪些工具、其中有多少次调用失败，以及服务器的配置。每份报告涵盖一个服务器进程，而非一个用户或一段对话；报告每隔 4h 发送一次，并在关闭时再发送一次。默认启用报告功能。如需选择退出，请设置 --usage-stats=disabled、GRAFANA_USAGE_STATS=disabled 或 DO_NOT_TRACK=1。

绝不会发送工具参数、资源名称、查询、日志行、错误消息或凭据。标志仅按名称记录，不记录其值；Grafana 实例仅描述为 cloud 或 self_hosted，绝不会包含 URL、主机名、堆栈 slug 或组织信息。所有数据都不按用户、会话或客户端区分：传输内容中没有会话标识符，也无法将某次工具调用归因于特定客户端。

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

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

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

DO_NOT_TRACK=1 也会禁用报告功能，遵循跨工具的 DO_NOT_TRACK 约定。只有 1 会生效，且只能禁用报告；--usage-stats 和 GRAFANA_USAGE_STATS 都会覆盖它，因此，即使主机全局设置了该变量，仍可单独为某个服务器重新启用报告。

GRAFANA_USAGE_STATS_ENDPOINT 可更改目标地址，但不会选择退出报告。

完整字段列表、绝不发送的数据、数据解读方式及其局限性，请参阅匿名使用统计。

可观测性

MCP 服务支持 Prometheus 指标、OpenTelemetry 分布式追踪和 OpenTelemetry 日志导出，并遵循 OTel MCP 语义约定。追踪和日志导出通过标准 OTEL_* 环境变量配置，并适用于任何传输方式。

**注意：**mcp-grafana 目前仅支持追踪和日志使用 OTLP/gRPC 传输。OTEL_EXPORTER_OTLP_PROTOCOL（及其 _TRACES_PROTOCOL / _LOGS_PROTOCOL 变体）不会生效——无论如何都会使用 gRPC。

指标

使用 SSE 或 streamable HTTP 传输时，可通过 --metrics 标志启用 Prometheus 指标：

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

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

可用指标：

指标	类型	描述
mcp_server_operation_duration_seconds	直方图	MCP 操作的耗时（标签：mcp_method_name、gen_ai_tool_name、error_type、network_transport、mcp_protocol_version）
http_server_request_duration_seconds	直方图	HTTP 服务请求的耗时（来自 otelhttp）

注意： 指标仅在使用 SSE 或 streamable HTTP 传输时可用。使用 stdio 传输时不可用。

启用 Loki 成本护栏（--loki-guardrail-mode）后，还会有四个计数器记录其决策：

指标	类型	描述
mcp_loki_guardrail_admitted_total	计数器	通过所有已启用检查的查询（标签：backend）
mcp_loki_guardrail_would_block_total	计数器	在 shadow 模式下未通过某项检查但仍继续执行的查询（标签：backend、reason）
mcp_loki_guardrail_blocked_total	计数器	在 enforce 模式下被拒绝的查询（标签：backend、reason）
mcp_loki_guardrail_fail_open_total	计数器	护栏无法评估但仍予以放行的查询（标签：backend、cause）

reason 的取值为 selector、range、bytes；cause 的取值为 unparseable、estimate_failed；backend 的取值为 loki、victorialogs、unknown。触发多项检查的查询只计数一次，并标记为最先运行的检查（依次为 selector、range、bytes），因此这四个计数器涵盖了所有受护栏保护的查询。有关在从 shadow 切换到 enforce 的过程中如何解读这些指标，请参阅可观测性。

嵌入该库的开发者应设置 GrafanaConfig.MeterProvider（它是 GrafanaConfig.Logger 对应的指标配置）：护栏在工具处理函数内部运行，因此没有构造函数选项；如果进程安装了 noop 全局 MeterProvider，否则所有记录都会被丢弃。

慢请求日志

--slow-request-threshold 标志会在 MCP 请求（工具调用、列表查询、资源读取等）耗时超过指定时长时，输出结构化日志事件。它有助于诊断缓慢的查询和工具调用，而无需淹没在完整的调试日志中。

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

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

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

日志事件包含以下结构化属性：

属性	描述
mcp.method	MCP 方法（例如 tools/call、tools/list、resources/read）
duration	实际请求耗时
threshold	配置的阈值
tool	工具名称（仅 tools/call 方法包含此属性）
error	请求失败时的错误值（尽力提供的上下文；内容由上游错误包装逻辑控制）
error.type	有界基数的错误分类（未类型化的错误为 _OTHER）

慢请求日志适用于所有传输方式（包括 stdio），且无需启用 --metrics。默认阈值 0 会完全禁用此功能。代理工具通过 tools/call 调用，因此会自动纳入记录。

链路追踪

分布式链路追踪通过标准 OTEL_* 环境变量配置，且独立于 --metrics 标志运行。设置 OTEL_EXPORTER_OTLP_ENDPOINT（或特定信号的 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT）后，服务会通过 OTLP/gRPC 导出链路追踪数据：

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

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

工具调用 Span 遵循 semconv 命名规范（tools/call <tool_name>），并包含 gen_ai.tool.name、mcp.method.name 和 mcp.session.id 等属性。服务还支持从工具调用请求的 _meta 字段传播 W3C 链路上下文。

日志

设置 OTEL_EXPORTER_OTLP_ENDPOINT（或特定信号的 OTEL_EXPORTER_OTLP_LOGS_ENDPOINT）后，服务器除了输出已有的纯文本 stderr 日志外，还会通过 OTLP/gRPC 导出结构化日志。otelslog 桥接程序会自动附加活动 span 的 trace_id 和 span_id，使日志记录能够与服务器已输出的追踪信息关联起来。

追踪和日志会分别解析各自的端点，因此可以单独启用这两种信号：仅设置 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT 可启用追踪，但不会导出日志；仅设置 OTEL_EXPORTER_OTLP_LOGS_ENDPOINT 可启用日志导出，但不会启用追踪；设置通用变量 OTEL_EXPORTER_OTLP_ENDPOINT 则会同时启用两者。

如果使用通用变量 OTEL_EXPORTER_OTLP_ENDPOINT，但想禁用日志导出（例如，你的后端不支持 LogsService），请设置：

OTEL_LOGS_EXPORTER=none

无论端点配置如何，此操作都会阻止服务器创建 OTLP 日志导出器，避免出现 unknown service opentelemetry.proto.collector.logs.v1.LogsService 等错误。

启用 OTLP 日志后，stderr 日志不受影响；你仍可依赖容器日志，或按需将 stderr 管道传输到 /dev/null。

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

传输协议为 OTLP/gRPC（默认端口 4317）。日志可直接发送到任何接受 OTLP/gRPC 的托管后端，例如 Grafana Cloud：将 OTEL_EXPORTER_OTLP_LOGS_ENDPOINT（或通用变量 OTEL_EXPORTER_OTLP_ENDPOINT）指向远程 gRPC 端点，并通过 OTEL_EXPORTER_OTLP_LOGS_HEADERS（或 OTEL_EXPORTER_OTLP_HEADERS）提供身份验证信息，方式与上面的追踪示例相同。本地 OTel 收集器可选，适用于扇出、批处理或多后端路由，但并非必需。

系统支持特定信号的变量 OTEL_EXPORTER_OTLP_LOGS_ENDPOINT、OTEL_EXPORTER_OTLP_LOGS_HEADERS、OTEL_EXPORTER_OTLP_LOGS_INSECURE、OTEL_EXPORTER_OTLP_LOGS_CERTIFICATE、OTEL_EXPORTER_OTLP_LOGS_TIMEOUT 和 OTEL_EXPORTER_OTLP_LOGS_COMPRESSION，这些变量会覆盖对应的通用 OTEL_EXPORTER_OTLP_* 变量。完整列表和优先级规则请参阅 OTel 导出器规范。

如果无法访问已配置的收集器，日志记录会缓存在内存中（默认队列大小：2048）；队列满后会丢弃最早的记录。进程会继续运行，不会阻塞服务。如需在中断期间无损缓冲，请配置本地 OTel 收集器。

在 stdio 传输下也会导出日志，因此可以轻松集中处理由 IDE 客户端调用的本地 mcp-grafana 实例日志。

包含指标、追踪和日志的 Docker 示例：

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

Loki 查询强制约束

--loki-enforced-matchers 允许操作员限制服务可以读取的 Loki 日志流。它会将一组固定的 LogQL 标签匹配器通过 AND 逻辑加入服务发出的每个原生 Loki 查询中。当数据源包含不得暴露的日志流（例如可能包含敏感信息的日志），但无法在 Grafana 或 Loki 层限制访问时，这项功能会很有用（开源版没有按数据源或用户控制标签访问权限的功能）。

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

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

工作原理：

• 启动时只解析一次匹配器（输入无效会导致服务启动中止），并将其追加到每个查询中的每个流选择器。由于 Loki 会对选择器内的匹配器进行 AND 运算，用户查询只能在强制约束范围内缩小结果范围，绝不可能扩大范围。与策略冲突的用户选择器（例如在排除规则下查询 {namespace="vault"}）只会返回空结果。
• 适用于 query_loki_logs、query_loki_stats、query_loki_patterns、list_loki_label_names 和 list_loki_label_values。
• 失败时默认拒绝：无法解析的查询会被拒绝，而不会未经筛选就发送。
• VictoriaLogs 数据源使用 LogsQL，无法安全地重写，因此启用强制约束时会被完全拒绝。
• 纯负向匹配器无法限定标签枚举端点的范围（Loki 会拒绝不含正向匹配器的独立选择器）。可通过 --loki-label-enumeration-fallback 控制这种边缘情况（默认值为 reject，也可设为 unfiltered，以允许不受范围限制地枚举标签元数据——日志行绝不会暴露）。正向／允许列表匹配器不受影响。

重要

强制约束只适用于 Loki 查询工具。其他工具可以通过不会经过受强制约束的后端的路径访问 Loki 日志数据，因此若要确保限制生效，还必须禁用这些工具：

• --disable-api — grafana_api_request 可以直接查询 Loki 数据源代理（完全绕过限制）。
• --disable-rendering — get_panel_image 会在服务端渲染 Loki 面板，生成包含未受限制日志行的图像。
• --disable-assistant — ask_assistant 会将请求交给 Grafana Assistant，由其在服务端读取所有流中的 Loki 数据。只有启用写入工具时才会注册，因此 --disable-write 也能将其关闭。

服务启动时会记录警告，列出其中仍处于启用状态的工具。 run_panel_query 是安全的（它会复用受强制约束的查询路径）。Tempo 工具查询的是跟踪数据，而非 Loki 日志，因此不会绕过限制。仪表板快照（--disable-snapshot）也可能嵌入在强制约束之外捕获的日志面板数据。

故障排除

Grafana 版本兼容性

如果使用数据源相关工具时遇到以下错误：

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

这通常表示你使用的 Grafana 版本早于 9.0。/datasources/uid/{uid} API 端点是在 Grafana 9.0 中引入的，因此在更早的版本中，数据源操作会失败。

**解决方案：**将 Grafana 实例升级到 9.0 或更高版本即可解决此问题。

开发

欢迎贡献！请先阅读 CONTRIBUTING.md——其中介绍了此服务中适合添加的内容以及如何提出建议。

如果要添加新工具，请在编写代码前提交工具提案。每个默认启用的工具都会在每次请求中发送给每位用户使用的模型，因此我们更愿意先讨论这个想法，而不是拒绝一份已经完成的拉取请求。错误修复、文档、测试以及现有工具的新参数都无需提案——直接提交 PR 即可。

此项目使用 Go 编写。工具版本和开发任务位于 mise.toml 中：安装 mise，运行 mise install 获取固定版本的工具，并运行 mise tasks 查看任务列表。

要在本地以 STDIO 模式运行服务（这是本地开发的默认模式），请使用：

mise run run

要在本地以 SSE 模式运行服务，请使用：

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

你也可以在自定义构建的 Docker 镜像中使用 SSE 传输运行服务。与已发布的 Docker 镜像一样，此自定义镜像的入口点默认使用 SSE 模式。要构建镜像，请使用：

mise run build-image

要以 SSE 模式（默认模式）运行镜像，请使用：

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

如果需要改用 STDIO 模式，请覆盖传输设置：

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

测试

共有三种测试：

1. 单元测试（无需外部依赖）：

mise run test-unit

你也可以通过以下命令运行单元测试：

mise run test

2. 集成测试（需要 Docker 容器处于运行状态）：

mise run test-integration

3. 云测试（需要云端 Grafana 实例和凭据）：

mise run test-cloud

注意：云测试会在 CI 中自动配置。在本地开发时，你需要自行设置 Grafana Cloud 实例和凭据。

更全面的集成测试需要本地运行 Grafana 实例，且端口为 3000；你可以使用 Docker Compose 启动实例：

docker-compose up -d

如果要添加更多工具，请为其添加集成测试。现有测试可以作为很好的起点。

代码检查

要检查代码，请运行：

mise run lint

其中包含一个自定义检查器，用于检查 jsonschema 结构体标签中是否有未转义的逗号。description 字段中的逗号必须使用 \\, 转义，以防止内容被静默截断。你可以通过以下命令单独运行此检查器：

mise run lint-jsonschema

更多详情请参阅 JSONSchema 检查器文档。

许可证

此项目采用 Apache License, Version 2.0 许可。