Grafana

官方

在您的Grafana实例中搜索仪表盘、调查事件并查询数据源

GitHub

3.7k

你可以用 Grafana MCP 做什么？

搜索和检查仪表板 — 按标题、文件夹、标签或收藏状态查找仪表板，然后通过 JSONPath 获取简要摘要或特定属性。
无需完整 JSON 即可修改仪表板 — 对现有仪表板进行定向修改，或通过完整 JSON 创建和更新仪表板。
查询 Prometheus 和 Loki — 运行 PromQL 指标查询和 LogQL 日志或指标查询，还可获取指标元数据、标签和日志模式。
查询 SQL 数据源 — 列出数据库、表和架构，描述表列，并对 ClickHouse、Snowflake、Athena、MySQL、PostgreSQL、MSSQL 或 BigQuery 运行 SQL。
管理告警和事件 — 列出、创建、更新和删除告警规则，查看通知策略和联系人，并搜索或更新 Grafana Incident 记录。
生成深层链接并渲染面板 — 构建准确的仪表板、面板和 Explore URL，并将面板或仪表板渲染为 PNG 图像。

文档

Grafana MCP server

用于 Grafana 的 Model Context Protocol (MCP) 服务器。

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

快速开始

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

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

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

要求

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

功能

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

仪表板

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

运行面板查询

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

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

上下文窗口管理

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

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

数据源

列出并获取数据源信息： 查看所有已配置的数据源，并检索每个数据源的详细信息。
- 支持的数据源类型：Prometheus、Loki、ClickHouse、CloudWatch、Elasticsearch、OpenSearch、Snowflake、Athena。
数据源资源： 你可以访问的每个数据源也会作为 MCP 资源公开在 grafana://datasources/{uid}，因此你可以直接将其附加到对话中（例如在 Claude Code 中使用 @），而无需让模型自行查找。与数据源工具一同禁用。

查询示例

注意： 查询示例工具默认处于禁用状态。要启用这些工具，请将 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 和 BigQuery。查询会通过 Grafana 的数据源插件执行，因此身份验证由数据源配置处理——MCP 服务器不会接触凭据。

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

对于 BigQuery，请在 Grafana 中配置 grafana-bigquery-datasource 插件。发现功能使用 database 获取项目，使用 schema 获取数据集。如果省略 database，项目将默认使用数据源的 defaultProject，然后使用插件的 /defaultProjects 端点（包括 GCE 项目发现）。元数据仅通过 API 获取，不会创建查询作业或扫描表。结果包含列描述和嵌套类型；插件不提供表描述/类型、列是否可为空的信息和默认值。

BigQuery 查询需要使用限定表引用，例如 `my-project.my_dataset.fct_events` and use the datasource's billing project. Optional location defaults to datasource processingLocation. Use ${name:sqlstring}，以转义字符串变量。行数限制不会限制扫描的字节数或查询成本。

CloudWatch 查询

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

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

Google Cloud Logging 查询

注意： Google Cloud Logging 工具默认处于禁用状态。要启用这些工具，请将 cloudlogging 添加到 --enabled-tools 标志中。需要使用 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 标志中。

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

Grafana Assistant

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

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

事件

搜索、创建和更新事件： 在 Grafana Incident 中管理事件，包括搜索、创建、添加活动，以及读取或设置自定义字段。
事件资源： 最近 30 天内开始的活动事件也会作为 MCP 资源公开在 grafana://irm/incidents/{id}，因此你可以直接将其附加到对话中（例如，在 Claude Code 中使用 @）。禁用事件工具时，这些资源也会一并禁用。

告警

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

Grafana OnCall

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

管理员

注意： 管理员工具默认处于禁用状态。要启用这些工具，请在 --enabled-tools 标志中加入 admin。

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

用户

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

生成深层链接： 为 Grafana 资源创建准确的深层链接 URL，而不是依赖 LLM 猜测 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 根据基本角色授权事件操作。

group/resource:verb 形式的操作（例如 dashboard.grafana.app/dashboards:get）仅适用于代表用户访问令牌。服务账号只需要其他列出的操作。

有关 Grafana RBAC 的更多信息，请参阅官方文档。

RBAC 范围

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

常见范围模式：

广泛访问： 使用 * 通配符，授予整个组织范围的访问权限
- datasources:* - 访问所有数据源
- dashboards:* - 访问所有仪表板
- folders:* - 访问所有文件夹
- teams:* - 访问所有团队
有限访问： 使用特定 UID 或 ID，将访问权限限制到单个资源
- datasources:uid:prometheus-uid - 仅访问特定的 Prometheus 数据源
- dashboards:uid:abc123 - 仅访问 UID 为 abc123 的仪表板
- folders:uid:xyz789 - 仅访问 UID 为 xyz789 的文件夹
- teams:id:5 - 仅访问 ID 为 5 的团队
- global.users:id:123 - 仅访问 ID 为 123 的用户

示例：

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

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

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

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

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

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

工具

工具	类别	描述	所需 RBAC 权限	所需范围
`list_teams`	管理员*	列出所有团队	`teams:read`	`teams:*` 或 `teams:id:1`
`list_users_by_org`	管理员*	列出组织中的用户，支持搜索和分页	`org.users:read`	`global.users:*` 或 `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`	用户	当前身份、功能和可访问的组织	None	—
`search_dashboards`	搜索	按查询、文件夹 UID、文件夹路径、标签或收藏状态搜索仪表板	`dashboards:read`, `folders:read`	`dashboards:*` 或 `dashboards:uid:abc123`
`search_folders`	搜索	按标题搜索文件夹	`folders:read`	`folders:*` 或 `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:` 或 `folders:uid:xyz789`
`get_dashboard_panel_queries`	仪表板	从仪表板获取面板标题、查询、数据源 UID 和类型	`dashboard.grafana.app/dashboards:get`, `dashboards:read`	`dashboards:uid:abc123`
`run_panel_query`	RunPanelQuery*	执行一个或多个仪表板面板查询	`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:*` 或 `datasources:uid:abc123`
`get_query_examples`	示例*	获取数据源类型的示例查询	None	`datasources:*`
`query_prometheus`	Prometheus	使用 PromQL 查询指标，无需打开图表	`datasources:query`, `datasources:read`	`datasources:uid:prometheus-uid`
`render_grafana_app`	渲染	运行已启用的查询工具，并在交互式 Grafana App 中显示其结果	`datasources:query`, `datasources:read`	`datasources:*` 或 `datasources:uid:<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`	Config	生成强制执行已批准标签的 Alloy `loki.process` 代码片段	None	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`	Alerting	列出并检查告警规则（list、get、versions）	`alert.rules.external:read`, `alert.rules:read`, `datasources:read`, `folders:read`	`folders:*` 或 `folders:uid:alerts-folder`
`alerting_rules_write`	Alerting	创建、更新和删除 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:*`，或用于外部创建的 `datasources:uid:<uid>`
`alerting_manage_routing`	Alerting	管理通知策略、联系点和时间间隔	`alert.notifications.external:read`, `alert.notifications.receivers:read`, `alert.notifications.routes:read`, `alert.notifications.time-intervals:read`, `alert.notifications:read`, `datasources:query`, `datasources:read`, `notifications.alerting.grafana.app/routingtrees:get`	全局范围
`alerting_routing_write`	Alerting	默认创建 Grafana 管理的联系点，或显式创建外部 Alertmanager 接收器	`alert.notifications.external:read`, `alert.notifications.external:write`, `alert.notifications.receivers:create`, `alert.provisioning.provenance:write`, `datasources:read`	全局，或用于外部创建的 `datasources:uid:<uid>`
`alerting_silences_read`	Alerting	列出并检查告警静默（list、get）	`alert.instances:read`, `alert.silences:read`	全局范围
`alerting_silences_write`	Alerting	创建、更新和使告警静默过期	`alert.instances:create`, `alert.instances:read`, `alert.instances:write`, `alert.silences:create`, `alert.silences:read`, `alert.silences:write`	全局范围
`list_oncall_schedules`	OnCall	列出 Grafana OnCall 中的排班	`grafana-irm-app.schedules:read`, `plugins.app:access`	插件专属范围
`get_oncall_shift`	OnCall	获取特定 OnCall 班次的详细信息	`grafana-irm-app.schedules:read`, `plugins.app:access`	插件专属范围
`get_current_oncall_users`	OnCall	获取特定排班中当前值班的用户	`grafana-irm-app.schedules:read`, `grafana-irm-app.user-settings:read`, `plugins.app:access`	插件专属范围
`list_oncall_teams`	OnCall	列出 Grafana OnCall 中的团队	`grafana-irm-app.user-settings:read`, `plugins.app:access`	插件专属范围
`list_oncall_users`	OnCall	列出 Grafana OnCall 中的用户	`grafana-irm-app.user-settings:read`, `plugins.app:access`	插件专属范围
`list_alert_groups`	OnCall	列出 Grafana OnCall 中的告警组，并提供筛选选项	`grafana-irm-app.alert-groups:read`, `plugins.app:access`	插件专属范围
`get_alert_group`	OnCall	根据 ID 获取 Grafana OnCall 中的特定告警组	`grafana-irm-app.alert-groups:read`, `plugins.app:access`	插件专属范围
`update_alert_group`	OnCall	确认、取消确认、解决或取消解决告警组	`grafana-irm-app.alert-groups:read`, `grafana-irm-app.alert-groups:write`, `plugins.app:access`	插件专属范围
`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`
`agento11y_manage_conversations`	Agent Observability*	列出、搜索并获取来自 Grafana Agent Observability 的 LLM 对话	`grafana-agento11y-app.conversations:read`, `grafana-agento11y-app.data:read`, `plugins.app:access`	不适用
`agento11y_manage_generations`	Agent Observability*	获取来自 Grafana Agent Observability 的 LLM 生成详情和评估分数	`grafana-agento11y-app.conversations:read`, `grafana-agento11y-app.data:read`, `plugins.app:access`	不适用
`agento11y_manage_agents`	Agent Observability*	读取代理目录：列出代理、完整获取某个代理版本、列出版本历史记录，以及按版本汇总分数	`grafana-agento11y-app.conversations:read`, `grafana-agento11y-app.data:read`, `plugins.app:access`	不适用
`agento11y_manage_evaluators`	Agent Observability*	管理评估器、评估器模板和评判器目录（列出、获取、插入或更新、派生、测试、删除）	`grafana-agento11y-app.conversations:read`, `grafana-agento11y-app.data:read`, `plugins.app:access`；启用写入后还包括 `grafana-agento11y-app.eval:write`	不适用
`agento11y_manage_eval_rules`	Agent Observability*	管理评估规则和防护措施（列出、获取、创建、更新、预览、删除）	`grafana-agento11y-app.conversations:read`, `grafana-agento11y-app.data:read`, `plugins.app:access`；启用写入后还包括 `grafana-agento11y-app.eval:write`	不适用
`agento11y_manage_eval_collections`	Agent Observability*	管理已保存的对话及其所属集合（列出、获取、保存、创建、更新、删除、添加和移除成员）	`grafana-agento11y-app.conversations:read`, `grafana-agento11y-app.data:read`, `plugins.app:access`；启用写入后还包括 `grafana-agento11y-app.eval:write`	不适用
`agento11y_manage_experiments`	Agent Observability*	读取离线实验、其实验试验、分数、制品元数据和筛选维度；更新和取消实验	`grafana-agento11y-app.conversations:read`, `grafana-agento11y-app.data:read`, `plugins.app:access`；启用写入后还包括 `grafana-agento11y-app.eval:write`	不适用
`agento11y_manage_test_suites`	Agent Observability*	管理离线实验所针对的测试套件、其版本和测试用例（列出、获取、创建、更新、起草、发布、插入或更新、删除）	`grafana-agento11y-app.conversations:read`, `grafana-agento11y-app.data:read`, `plugins.app:access`；启用写入后还包括 `grafana-agento11y-app.eval:write`	不适用
`ask_assistant`	Assistant*	向 Grafana Assistant 发送提示并返回完整文本回复（通过 `contextId` 实现多轮对话）	`grafana-assistant-app.chats:access`, `plugins.app:access`	插件专属范围
`generate_deeplink`	导航	为 Grafana 资源生成准确的深层链接 URL	无	不适用
`get_annotations`	注释	使用筛选条件获取注释	`annotations:read`	`annotations:*` 或 `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`	不适用
`get_snapshot`	快照	按快照键获取快照元数据和仪表板负载	无	不适用
`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`	不适用
`validate_provisioning_file`	Provisioning	对 provisioning 仓库中的文件执行试运行应用，并报告准入验证错误	`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`	Docs	搜索 Grafana 文档或列出产品组（省略查询以列出产品）	None	N/A
`get_doc`	Docs	获取文档页面；设置 outline_only 以获取标题，或设置 section 以限定检索范围	None	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	列出 span 和资源属性名称	`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 文档	None	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	获取已安装的插件	`plugins.app:access`	N/A
`search_plugin_information`	Plugins	搜索 grafana.com 插件目录	None	N/A
`install_plugin`	Plugins	安装插件	`plugins:install`	N/A
`grafana_api_request`	API	调用 Grafana HTTP API 端点	None	取决于端点
* 默认禁用。将类别添加到 `--enabled-tools` 以启用。

当启用渲染类别和相应的查询类别时，render_grafana_app 工具会在兼容的 MCP 主机中显示指标和追踪。源查询工具会返回文本和结构化数据以供分析。有关设置和库嵌入，请参阅 MCP Apps。

CLI 标志参考

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

传输选项：

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

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

HTTP 传输安全（仅限 SSE / streamable-http）：

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

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

[!WARNING] URL 覆盖允许 MCP 调用方选择出站 HTTP(S) 目标。允许列表可以限制 URL，但不能对调用方进行身份验证，也不能将令牌绑定到目标。

请部署在经过身份验证的代理之后，由该代理授权每个目标、替换客户端提供的 URL 和令牌标头，并提供匹配的令牌。限制服务器的出站网络访问范围，仅允许访问获准的目标。

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

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

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

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

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

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

对于选定的 URL，服务器不会使用 GRAFANA_SERVICE_ACCOUNT_TOKEN、GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE、GRAFANA_API_KEY、环境基本身份验证、GRAFANA_EXTRA_HEADERS 或客户端证书。即使设置了 --tls-skip-verify，TLS 验证仍会启用；已配置的 CA 文件仍然适用。该请求中显式转发的标头仍然适用。重定向以及选定基础 URL 之外的其他 Grafana API 请求都会被阻止。不带 X-Grafana-URL 的请求仍使用常规的 GRAFANA_URL 和环境凭据行为。此选项仅适用于 streamable HTTP。它不适用于 SSE，因为 SSE 不会将每个请求的标头传递给工具调用；在 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 span 中包含工具调用参数。仅在非生产环境中启用，或在确认参数不包含 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。
--prometheus-guardrail-mode：针对 query_prometheus、query_prometheus_histogram 以及 run_panel_query 中 Prometheus 查询的防护 - 默认：off。此防护会在查询到达数据源之前，限制查询的有效时间范围以及每个序列请求的点数。可独立选择启用选择器策略，要求每个向量选择器除指标名称外，还必须包含非空的正向标签约束；示例和限制请参阅选择器策略。shadow 会记录将被阻止的查询，但仍允许其运行；enforce 会拒绝这些查询，并提供 LLM 可据此采取行动的改写建议（run_panel_query 会在该面板结果的 errors 条目中报告此情况）。环境变量回退：GRAFANA_PROMETHEUS_GUARDRAIL_MODE。
--prometheus-guardrail-require-selective-labels：要求每个向量选择器除指标名称外，还必须包含非空的正向标签约束。默认：false；独立于范围和点数预算，即使两者均为 0 也不例外。仅当防护模式不是 off 时才适用。环境变量回退：GRAFANA_PROMETHEUS_GUARDRAIL_REQUIRE_SELECTIVE_LABELS。显式 CLI 值（包括 false）优先于环境变量。
--prometheus-guardrail-max-range：单个 PromQL 查询的最大有效时间范围 - 默认：192h。有效范围是查询自身的时间范围（即时查询为零）加上表达式中最长的范围向量或子查询窗口；嵌套子查询的范围会累加，因此 max_over_time(rate(x[5m])[30d:1m]) 表示 30d5m。接受 Go 时长字符串，因此应写作 192h，而不是 8d。0 会禁用范围检查。环境变量回退：GRAFANA_PROMETHEUS_GUARDRAIL_MAX_RANGE。
--prometheus-guardrail-max-points：范围查询每个序列可请求的最大点数，floor(range / step) + 1 - 默认：11000，即 Prometheus 自身的每序列限制。建议会指出满足要求的最小 stepSeconds。0 会禁用点数检查。环境变量回退：GRAFANA_PROMETHEUS_GUARDRAIL_MAX_POINTS。

Prometheus 防护的限制：点数检查针对请求的分辨率进行预算，而非序列数、样本数或子查询求值次数；Grafana 也可能对齐范围或扩大步长。offset 和 @ 修饰符会被忽略。$__rate_interval 和 $__range 等 Grafana 宏会在测量表达式前填充为 Grafana 使用的值（$__rate_interval 是步长的四倍）。对于防护仍无法解析的表达式（例如包含 $window 等仪表板变量的表达式，或仅被其他方言接受的语法），只会根据查询自身的时间范围和步长进行检查，否则照常运行。run_panel_query 没有步长参数，因此对于较长时间范围，它会像 Grafana 一样扩大其 1 分钟步长，以保持在 11000 个点以内；在 enforce 模式下，也会保持在较低的 --prometheus-guardrail-max-points 以内。
--loki-enforced-matchers：与每个原生 Loki 查询进行 AND 运算的 LogQL 标签匹配器，用于限制可读取的日志流（例如 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 下继续工作，而 --enable-write-tools=alerting_rules_write 可在不启用其他写入工具的情况下允许更改告警规则。
--disable-loki：禁用 Loki 工具
--disable-elasticsearch：禁用 Elasticsearch 和 OpenSearch 工具
--disable-quickwit：禁用 Quickwit 工具
--disable-influxdb：禁用 InfluxDB 工具
--disable-alerting：禁用告警工具
--disable-dashboard：禁用仪表板工具
--disable-oncall：禁用 OnCall 工具
--disable-asserts：禁用断言工具
--disable-admin：禁用管理工具
--disable-pyroscope：禁用 Pyroscope 工具
--disable-navigation：禁用导航工具
--disable-rendering：禁用渲染工具（面板/仪表板图像导出）
--disable-snapshot：禁用快照工具
--disable-cloudwatch：禁用 CloudWatch 工具
--disable-cloudlogging：禁用 Google Cloud Logging 工具
--disable-examples：禁用查询示例工具
--disable-sql：禁用 SQL 数据源工具（ClickHouse、Snowflake、Athena、MySQL、PostgreSQL、MSSQL、BigQuery）。别名 --disable-clickhouse、--disable-snowflake、--disable-athena 也可用。
--disable-runpanelquery：禁用运行面板查询工具
--disable-graphite：禁用 Graphite 工具
--disable-provisioning：禁用配置工具
--disable-agento11y：禁用 Agent Observability 工具
--disable-assistant：禁用 Grafana Assistant 工具
--disable-docs：禁用文档工具

只读模式

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

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

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

仪表板工具：

update_dashboard

文件夹工具：

create_folder

事件工具：

create_incident
add_activity_to_incident
update_incident

告警工具：

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

可通过 --enable-write-tools=<name> 单独保留每个告警写入工具。

OnCall 工具：

update_alert_group

注释工具：

create_annotation
update_annotation
delete_annotation

快照工具：

create_snapshot
delete_snapshot

导航工具：

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

原始 SQL 查询工具：

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

query_sql
query_influxdb

Agent Observability 工具：

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

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

无查询模式

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

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

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

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

Prometheus 工具：

query_prometheus
query_prometheus_histogram

渲染工具：

render_grafana_app

Loki 工具：

query_loki_logs
query_loki_patterns

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

Elasticsearch/OpenSearch 和 Quickwit 工具：

query_elasticsearch
query_quickwit

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

query_influxdb SQL 数据源工具（也由 --disable-write 移除，见上文）：
query_sql

Graphite 工具：

query_graphite
query_graphite_density

CloudWatch 工具：

query_cloudwatch
query_cloudwatch_logs

Google Cloud Logging 工具：

query_cloud_logging

Pyroscope 工具：

query_pyroscope

运行面板查询工具：

run_panel_query

elasticsearch、quickwit、influxdb 和 runpanelquery 类别不包含其他内容，因此禁用查询时不会注册任何工具。其他所有类别中的同级工具——list_prometheus_metric_names、list_loki_label_values、describe_sql_table、list_cloudwatch_metrics、list_cloud_logging_projects 等——仍然可用。

请注意，--disable-query 会控制查询工具和 grafana_api_request 到 /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。

如果使用服务账号令牌身份验证，请在 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 标头：**使用 streamable HTTP 传输时设置 X-Grafana-Org-Id（标头优先于环境变量，因此您也可以设置默认组织）。

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

动态（按调用）选择组织

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

启用后，每个工具都会接受可选的 orgId 参数，用于覆盖该次调用的连接组织（同时设置 X-Grafana-Org-Id 标头，并为应用平台 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:pass@127.0.0.1:1080。

示例：

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

无效的代理 URL 会导致启动错误；如果运行时无法建立代理连接，服务器会采取故障关闭策略，而不会悄悄直接发送 Grafana 流量。

转发客户端标头（仅适用于 Streamable-HTTP）

当 MCP 服务器运行在处理 SSO 的网关或反向代理之后（例如使用 OIDC 的 AWS ALB）时，必须将每位用户的会话 Cookie 传递给 Grafana，以便 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）是例外：服务器会自行传播跟踪上下文，因此转发的值不会覆盖服务器注入的值。请参阅可观测性。

安装 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
# For local Grafana:
docker run --rm -i -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> grafana/mcp-grafana -t stdio
# For Grafana Cloud:
docker run --rm -i -e GRAFANA_URL=https://myinstance.grafana.net -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> grafana/mcp-grafana -t stdio
```
  注意——保护网络模式：在 SSE 和 streamable-http 模式下，容器会绑定到非回环地址（0.0.0.0:8000）。如果未设置调用方令牌，服务器仍会启动，但会记录安全错误（日志级别为 error，因此不会被 --log-level 隐藏；未来的主要版本中将拒绝启动）。请设置 MCP_GRAFANA_SERVER_TOKEN，要求客户端提供 Authorization: Bearer <token>（推荐）。STDIO 模式不受影响。请参阅调用方身份验证。
  1. SSE 模式：在此模式下，服务器作为 HTTP 服务器运行，客户端可连接到该服务器。必须使用 -p 标志公开端口 8000：
```
docker pull grafana/mcp-grafana
docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> -e MCP_GRAFANA_SERVER_TOKEN=<caller auth token> grafana/mcp-grafana
```
  1. Streamable HTTP 模式：在此模式下，服务器作为独立进程运行，可处理多个客户端连接。必须使用 -p 标志公开端口 8000。此模式下必须通过 -t streamable-http 显式覆盖默认设置。
```
docker pull grafana/mcp-grafana
docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> -e MCP_GRAFANA_SERVER_TOKEN=<caller auth token> grafana/mcp-grafana -t streamable-http
```
  使用服务器 TLS 证书启用 HTTPS streamable HTTP 模式：
```
docker pull grafana/mcp-grafana
docker run --rm -p 8443:8443 \
  -v /path/to/certs:/certs:ro \
  -e GRAFANA_URL=http://localhost:3000 \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> \
  -e MCP_GRAFANA_SERVER_TOKEN=<caller auth token> \
  grafana/mcp-grafana \
  -t streamable-http \
  -addr :8443 \
  --server.tls-cert-file /certs/server.crt \
  --server.tls-key-file /certs/server.key
```
- 下载二进制文件：从发布页面下载最新版本的 mcp-grafana，并将其放入 $PATH。
- 从源代码构建：如果已安装 Go 工具链，也可以从源代码构建并安装。使用 GOBIN 环境变量指定二进制文件的安装目录。该目录也应位于 $PATH 中。
```
GOBIN="$HOME/go/bin" go install github.com/grafana/mcp-grafana/v2/cmd/mcp-grafana@latest
```
- 使用 Helm 部署到 Kubernetes：使用 Grafana helm-charts 仓库中的 Helm 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
```

将服务器配置添加到客户端配置文件中。以 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 报告自身的匿名使用统计信息：调用了哪些工具、其中有多少次调用失败，以及服务器的配置方式。每份报告涵盖一个服务器进程，而非一个用户或一次对话；报告每 4 小时发送一次，并在关闭时再发送一次。默认启用报告功能。如需选择退出，请设置 --usage-stats=disabled、GRAFANA_USAGE_STATS=disabled 或 DO_NOT_TRACK=1。

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

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

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

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

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

GRAFANA_USAGE_STATS_ENDPOINT 会更改目标位置，而不是选择退出。

有关完整字段列表、绝不会发送的内容、数据读取方式及其局限性，请参阅匿名使用统计信息。

可观测性

MCP 服务器支持 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 推出期间如何解读这些指标，请参阅可观测性。

启用 Prometheus 防护机制（--prometheus-guardrail-mode）后，也会以相同方式使用四个计数器记录其决策：

指标	类型	描述
`mcp_prometheus_guardrail_admitted_total`	计数器	通过所有已启用检查的查询
`mcp_prometheus_guardrail_would_block_total`	计数器	在 `shadow` 模式下未通过检查但仍继续执行的查询（标签：`reason`）
`mcp_prometheus_guardrail_blocked_total`	计数器	在 `enforce` 模式下被拒绝的查询（标签：`reason`）
`mcp_prometheus_guardrail_fail_open_total`	计数器	防护机制无法解析其表达式但仍予以放行的查询（标签：`reason`）

在 would_block 和 blocked 上，reason 是 range 或 points，按第一个未通过的检查计数一次（依次为 range、points）；在 fail_open 上则为 unparseable。没有 backend 标签：所有兼容 Prometheus 的后端都会执行相同的检查。

库的嵌入者应设置 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 遵循语义约定命名（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）后，服务器还会通过 OTLP/gRPC 导出结构化日志，同时保留现有的纯文本 stderr 输出。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）。只需将 OTEL_EXPORTER_OTLP_LOGS_ENDPOINT（或通用变量 OTEL_EXPORTER_OTLP_ENDPOINT）指向远程 gRPC 端点，并通过 OTEL_EXPORTER_OTLP_LOGS_HEADERS（或 OTEL_EXPORTER_OTLP_HEADERS）提供身份验证，即可将日志直接发送到任何接受 OTLP/gRPC 的托管后端，例如 Grafana Cloud；配置方式与上文的追踪示例相同。本地 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 层限制访问时（OSS 没有按数据源或用户设置的标签访问控制），这项功能就很有用。

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

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

工作原理：

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

[!IMPORTANT] 强制策略仅适用于 Loki 查询工具。其他工具可以通过不会经过强制策略后端的路径访问 Loki 日志数据，因此要确保限制真正生效，还必须禁用这些工具：

--disable-api — grafana_api_request 可以直接查询 Loki 数据源代理（完全绕过限制）。

--disable-rendering — get_panel_image 会在服务器端渲染 Loki 面板，生成包含未受限制日志行的图像。

--disable-assistant — ask_assistant 会委托给 Grafana Assistant，由其在服务器端读取所有流中的 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

测试

有三种类型的测试可用：

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

mise run test-unit

你也可以使用以下命令运行单元测试：

mise run test

集成测试（需要 Docker 容器正在运行）：

mise run test-integration

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

mise run test-cloud

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

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

docker-compose up -d

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

代码检查

要检查代码，请运行：

mise run lint

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

mise run lint-jsonschema

更多详情请参阅 JSONSchema Linter 文档。

许可证

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