Grafana

官方

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

GitHub

3.3k

你可以用 Grafana MCP 做什么？

搜索和检查仪表盘 — 按标题查找仪表盘，通过 get_dashboard_summary 获取紧凑摘要，或使用 get_dashboard_property 配合 JSONPath 提取特定部分。
查询数据源 — 通过 Grafana 实例对 Prometheus 运行 PromQL、对 Loki 运行 LogQL，或对 ClickHouse、Snowflake、Athena 等运行 SQL。
管理告警 — 列出告警规则及其状态，创建或更新规则，并查看通知策略和联系点。
生成深度链接 — 为仪表盘、面板和 Explore 视图创建包含时间范围和自定义参数的准确 URL，无需猜测链接。
渲染仪表盘图像 — 获取面板或整个仪表盘为 base64 编码的 PNG，支持尺寸、时间范围和主题选项。
管理事件和值班 — 在 Grafana OnCall 中搜索和创建事件，查看值班安排和当前用户，并列出告警组。

文档

Grafana MCP 服务器

一个用于 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 获取仪表板： 使用其唯一标识符检索完整的仪表板详情。警告：大型仪表板可能占用大量上下文窗口空间。
获取仪表板摘要： 获取仪表板的紧凑概览，包括标题、面板数量、面板类型、变量和元数据，而无需完整的 JSON，以尽量减少上下文窗口的使用
获取仪表板属性： 使用 JSONPath 表达式（例如 $.title、$.panels[*].title）提取仪表板的特定部分，仅获取所需数据并减少上下文窗口消耗
更新或创建仪表板： 修改现有仪表板或创建新仪表板。警告：需要完整的仪表板 JSON，这可能会占用大量上下文窗口空间。
修补仪表板： 对仪表板应用特定更改，无需完整的 JSON，从而显著减少针对性修改时的上下文窗口使用
获取面板查询和数据源信息： 获取仪表板中每个面板的标题、查询字符串和数据源信息（包括 UID 和类型，如果可用）

运行面板查询

注意： 运行面板查询工具默认禁用。要启用它们，请将 runpanelquery 添加到你的 --enabled-tools 标志中。

运行面板查询： 使用自定义时间范围和变量覆盖来执行仪表板面板的查询。

上下文窗口管理

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

使用 get_dashboard_summary 进行仪表板概览和规划修改
使用 get_dashboard_property 配合 JSONPath，当你只需要仪表板的特定部分时
避免 get_dashboard_by_uid，除非你特别需要完整的仪表板 JSON

数据源

列出和获取数据源信息： 查看所有已配置的数据源并检索每个数据源的详细信息。
- 支持的数据源类型：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 参数显式设置。

ClickHouse 查询

注意： ClickHouse 工具默认禁用。要启用它们，请将 clickhouse 添加到你的 --enabled-tools 标志中。

列出 ClickHouse 表： 列出 ClickHouse 数据库中的所有表，包括行数和大小。
描述表结构： 获取 ClickHouse 表的列名、类型和元数据。
查询 ClickHouse： 执行支持 Grafana 宏和变量替换的 SQL 查询。

CloudWatch 查询

注意： CloudWatch 工具默认禁用。要启用它们，请将 cloudwatch 添加到你的 --enabled-tools 标志中。

列出 CloudWatch 命名空间： 发现可用的 AWS CloudWatch 命名空间。
列出 CloudWatch 指标： 列出特定命名空间中可用的指标。
列出 CloudWatch 维度： 获取用于过滤指标查询的维度。
查询 CloudWatch： 执行支持时间范围的 CloudWatch 指标查询。

Graphite 查询

注意： Graphite 工具默认禁用。要启用它们，请将 graphite 添加到你的 --enabled-tools 标志中。

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

Athena 查询

注意： Athena 工具默认禁用。要启用它们，请将 athena 添加到你的 --enabled-tools 标志中。

列出 Athena 目录： 发现可用的数据目录（例如 AwsDataCatalog、Iceberg 连接器）。
列出 Athena 数据库： 列出 Athena 目录中的数据库。
列出 Athena 表： 列出 Athena 数据库中的表。
描述 Athena 表： 获取 Athena 表的列名。
查询 Athena： 通过 Grafana 对 Amazon Athena 执行 SQL 查询，支持宏替换、限制强制和模板变量支持。

Snowflake 查询

注意： Snowflake 工具默认禁用。要启用它们，请将 snowflake 添加到你的 --enabled-tools 标志中。

查询通过 Grafana 的 Snowflake 数据源（Grafana Enterprise 插件 grafana-snowflake-datasource）进行，因此身份验证由 Grafana 中的数据源配置处理——凭据永远不会被 MCP 服务器看到。这与 ClickHouse 工具使用的模式相同。

列出 Snowflake 表： 通过 INFORMATION_SCHEMA.TABLES 发现表（包括数据库、架构、种类、行数和大小）。可选的数据库/架构过滤器。
描述表结构： 获取 Snowflake 表的列名、数据类型、可空性、默认值和注释。
查询 Snowflake： 执行支持宏和变量替换的 SQL 查询。适用于查询 Snowflake 的事件表（例如 SNOWFLAKE.TELEMETRY.EVENTS）以获取日志和跟踪，或任何用户表。
- 支持的宏：$__timeFilter(column)、$__timeFrom、$__timeTo、$__from、$__to（Unix 毫秒）、$__interval（秒）、$__interval_ms 和 ${varname} 用于模板变量替换。

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 获取单个生成，及其评估分数（评估器、分数键、值、通过、说明）。
读取 Agent 目录： 列出发送遥测数据的代理，完整获取一个代理版本（完整的系统提示、每个工具及其 JSON 架构，以及其运行模型），浏览代理的版本历史，并比较每个版本的评估分数聚合。有效版本是 sha256: 哈希，工具更改永远不会影响它；对于不报告自身版本的代理，它们对系统提示进行哈希，因此提示编辑会产生新版本。目录和版本行带有 token_estimate，在获取完整提示之前值得检查。
检查评估器和模板： 读取分数来源的评估器、它们派生的模板，以及可用于 LLM 判断评估器的判断提供程序和模型。启用写入工具后，还可以创建、派生、测试和删除评估器。
检查评估规则和防护： 读取将评估器绑定到生产流量的异步评估规则，以及内联运行且可以警告或拒绝的防护（钩子规则）。启用写入工具后，还可以创建、更新、预览和删除它们。写入以及非持久化的 preview_rule 和 test_evaluator 操作需要 grafana-agento11y-app.eval:write 权限，由 Agento11y Admin 角色授予。
整理保存的对话和集合： 读取保存的对话（为对话提供稳定 ID、名称和标签的书签）以及对它们进行分组的集合，包括每个集合的成员计数以及嵌入在每个保存的对话行中的集合。启用写入工具后，还可以将对话加入书签、创建和编辑集合，以及添加或删除成员。这些写入需要相同的 grafana-agento11y-app.eval:write 权限。

Grafana Assistant

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

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

事件

搜索、创建和更新事件： 管理 Grafana Incident 中的事件，包括搜索、创建以及向事件添加活动。

Sift 调查

列出 Sift 调查： 获取 Sift 调查列表，支持 limit 参数。
获取 Sift 调查： 通过 UUID 获取特定 Sift 调查的详细信息。
获取 Sift 分析： 从 Sift 调查中获取特定分析。
在日志中查找错误模式： 使用 Sift 检测 Loki 日志中的异常错误模式。
查找慢请求： 使用 Sift（Tempo）检测慢请求。

告警

列出并获取告警规则信息： 查看 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 资源创建准确的深度链接 URL，而不是依赖 LLM 猜测 URL。
- 仪表盘链接： 使用仪表盘的 UID 生成直接链接（例如 http://localhost:3000/d/dashboard-uid）
- 面板链接： 使用 viewPanel 参数创建指向仪表盘内特定面板的链接（例如 http://localhost:3000/d/dashboard-uid?viewPanel=5）
- 探索链接： 生成带有预配置数据源的 Grafana Explore 链接（例如 http://localhost:3000/explore?left={"datasource":"prometheus-uid"}）
- 时间范围支持： 向链接添加时间范围参数（from=now-1h&to=now）
- 自定义参数： 包含其他查询参数，如仪表盘变量或刷新间隔

注解

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

快照

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

渲染

获取面板或仪表盘图像： 将 Grafana 仪表盘面板或整个仪表盘渲染为 PNG 图像。返回 base64 编码的图像数据，用于报告、告警或演示文稿。支持自定义尺寸、时间范围、主题、缩放比例和仪表盘变量。还支持通过可选的 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 服务器操作；它不如手动应用的范围那样精细（因此限制性较弱），因此仅在便利性比严格的最低权限访问更重要时使用它。

注意： Grafana Incident 和 Sift 工具使用基本的 Grafana 角色，而非细粒度的 RBAC 权限：

查看者角色： 只读操作所需（列出事件、获取调查）
编辑者角色： 写入操作所需（创建事件、修改调查）

有关 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`	Admin	列出所有团队	`teams:read`	`teams:*` 或 `teams:id:1`
`list_users_by_org`	Admin	列出组织中的所有用户	`users:read`	`global.users:*` 或 `global.users:id:123`
`list_all_roles`	Admin	列出所有 Grafana 角色	`roles:read`	`roles:*`
`get_role_details`	Admin	获取 Grafana 角色的详细信息	`roles:read`	`roles:uid:editor`
`get_role_assignments`	Admin	列出角色的分配情况	`roles:read`	`roles:uid:editor`
`list_user_roles`	Admin	列出用户的角色	`roles:read`	`global.users:id:123`
`list_team_roles`	Admin	列出团队的角色	`roles:read`	`teams:id:7`
`get_resource_permissions`	Admin	列出资源的权限	`permissions:read`	`dashboards:uid:abcd1234`
`get_resource_description`	Admin	描述 Grafana 资源类型	`permissions:read`	`dashboards:*`
`search_dashboards`	Search	搜索仪表盘	`dashboards:read`	`dashboards:*` 或 `dashboards:uid:abc123`
`get_dashboard_by_uid`	Dashboard	按 UID 获取仪表盘	`dashboards:read`	`dashboards:uid:abc123`
`update_dashboard`	Dashboard	更新或创建新仪表盘	`dashboards:create`、`dashboards:write`	`dashboards:`、`folders:` 或 `folders:uid:xyz789`
`get_dashboard_panel_queries`	Dashboard	从仪表盘中获取面板标题、查询、数据源 UID 和类型	`dashboards:read`	`dashboards:uid:abc123`
`run_panel_query`	RunPanelQuery*	执行一个或多个仪表盘面板查询	`dashboards:read`、`datasources:query`	`dashboards:uid:`、`datasources:uid:`
`get_dashboard_property`	Dashboard	使用 JSONPath 表达式提取仪表盘的特定部分	`dashboards:read`	`dashboards:uid:abc123`
`get_dashboard_summary`	Dashboard	获取仪表盘的紧凑摘要（不含完整 JSON）	`dashboards:read`	`dashboards:uid:abc123`
`list_datasources`	Datasources	列出数据源	`datasources:read`	`datasources:*`
`get_datasource`	Datasources	按 UID 或名称获取数据源	`datasources:read`	`datasources:uid:prometheus-uid`
`get_query_examples`	Examples*	获取数据源类型的示例查询	`datasources:read`	`datasources:*`
`query_prometheus`	Prometheus	针对 Prometheus 数据源执行查询	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_metric_metadata`	Prometheus	列出指标元数据	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_metric_names`	Prometheus	列出可用的指标名称	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_label_names`	Prometheus	列出与选择器匹配的标签名称	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_label_values`	Prometheus	列出特定标签的值	`datasources:query`	`datasources:uid:prometheus-uid`
`query_prometheus_histogram`	Prometheus	计算直方图百分位值	`datasources:query`	`datasources:uid:prometheus-uid`
`list_incidents`	Incident	列出 Grafana Incident 中的事件	查看者角色	不适用
`create_incident`	Incident	在 Grafana Incident 中创建事件	编辑者角色	不适用
`add_activity_to_incident`	Incident	在 Grafana Incident 中向事件添加活动项	编辑者角色	不适用
`get_incident`	Incident	按 ID 获取单个事件	查看者角色	不适用
`query_loki_logs`	Loki	使用 LogQL 查询和检索日志（日志或指标查询）	`datasources:query`	`datasources:uid:loki-uid`
`list_loki_label_names`	Loki	列出日志中所有可用的标签名称	`datasources:query`	`datasources:uid:loki-uid`
`list_loki_label_values`	Loki	列出特定日志标签的值	`datasources:query`	`datasources:uid:loki-uid`
`query_loki_stats`	Loki	获取日志流的统计信息	`datasources:query`	`datasources:uid:loki-uid`
`query_loki_patterns`	Loki	查询检测到的日志模式以识别常见结构	`datasources:query`	`datasources:uid:loki-uid`
`analyze_loki_labels`	Loki	审计 Loki 标签策略（实时或静态），并可选择诊断查询性能	`datasources:query`	`datasources:uid:loki-uid`
`suggest_loki_alloy_label_config`	Config	生成强制执行已批准标签的 Alloy `loki.process` 代码片段	不适用	不适用
`query_influxdb`	InfluxDB	使用 InfluxQL（v1）或 Flux（v2）查询 InfluxDB	`datasources:query`	`datasources:uid:influxdb-uid`
`list_clickhouse_tables`	ClickHouse*	列出 ClickHouse 数据库中的表	`datasources:query`	`datasources:uid:*`
`describe_clickhouse_table`	ClickHouse*	获取包含列类型的表结构	`datasources:query`	`datasources:uid:*`
`query_clickhouse`	ClickHouse*	使用宏替换执行 SQL 查询	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_namespaces`	CloudWatch*	列出可用的 AWS CloudWatch 命名空间	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_metrics`	CloudWatch*	列出命名空间中的指标	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_dimensions`	CloudWatch*	列出指标的维度	`datasources:query`	`datasources:uid:*`
`query_cloudwatch`	CloudWatch*	执行 CloudWatch 指标查询	`datasources:query`	`datasources:uid:*`
`list_athena_catalogs`	Athena*	列出可用的 Athena 数据目录	`datasources:query`	`datasources:uid:*`
`list_athena_databases`	Athena*	列出 Athena 目录中的数据库	`datasources:query`	`datasources:uid:*`
`list_athena_tables`	Athena*	列出 Athena 数据库中的表	`datasources:query`	`datasources:uid:*`
`describe_athena_table`	Athena*	获取 Athena 表的列名	`datasources:query`	`datasources:uid:*`
`query_athena`	Athena*	使用宏替换执行 SQL 查询	`datasources:query`	`datasources:uid:*`
`query_elasticsearch`	Elasticsearch/OpenSearch*	使用 Lucene 语法或查询 DSL 查询 Elasticsearch 或 OpenSearch	`datasources:query`	`datasources:uid:datasource-uid`
`query_quickwit`	Quickwit*	使用 Lucene 语法或查询 DSL 查询 Quickwit	`datasources:query`	`datasources:uid:quickwit-uid`
`list_snowflake_tables`	Snowflake*	通过 INFORMATION_SCHEMA 列出 Snowflake 数据库/模式中的表	`datasources:query`	`datasources:uid:*`
`describe_snowflake_table`	Snowflake*	获取表结构（列类型、可空性、默认值、注释）	`datasources:query`	`datasources:uid:*`
`query_snowflake`	Snowflake*	使用宏/变量替换执行 SQL 查询	`datasources:query`	`datasources:uid:*`
`alerting_manage_rules`	Alerting	管理警报规则（列出、获取、版本、创建、更新、删除）	`alert.rules:read` + `alert.rules:write` 用于变更操作	`folders:*` 或 `folders:uid:alerts-folder`
`alerting_manage_routing`	Alerting	管理通知策略、联系点和时间间隔	`alert.notifications:read`	全局范围
`list_oncall_schedules`	OnCall	从 Grafana OnCall 列出排班	`grafana-oncall-app.schedules:read`	插件特定范围
`get_oncall_shift`	OnCall	获取特定 OnCall 轮班的详细信息	`grafana-oncall-app.schedules:read`	插件特定范围
`get_current_oncall_users`	OnCall	获取当前在特定排班中值班的用户	`grafana-oncall-app.schedules:read`	插件特定范围
`list_oncall_teams`	OnCall	从 Grafana OnCall 列出团队	`grafana-oncall-app.user-settings:read`	插件特定范围
`list_oncall_users`	OnCall	从 Grafana OnCall 列出用户	`grafana-oncall-app.user-settings:read`	插件特定范围
`list_alert_groups`	OnCall	从 Grafana OnCall 列出带有过滤选项的警报组	`grafana-oncall-app.alert-groups:read`	插件特定范围
`get_alert_group`	OnCall	按 ID 从 Grafana OnCall 获取特定警报组	`grafana-oncall-app.alert-groups:read`	插件特定范围
`get_sift_investigation`	Sift	按 UUID 检索现有的 Sift 调查	查看者角色	不适用
`get_sift_analysis`	Sift	从 Sift 调查中检索特定分析	查看者角色	不适用
`list_sift_investigations`	Sift	检索 Sift 调查列表，可带可选限制	查看者角色	不适用
`find_error_pattern_logs`	Sift	发现 Loki 日志中的错误模式。	编辑者角色	不适用
`find_slow_requests`	Sift	从相关的 tempo 数据源中发现慢请求。	编辑者角色	不适用
`list_pyroscope_label_names`	Pyroscope	列出匹配选择器的标签名称	`datasources:query`	`datasources:uid:pyroscope-uid`
`list_pyroscope_label_values`	Pyroscope	列出匹配选择器的标签名称对应的标签值	`datasources:query`	`datasources:uid:pyroscope-uid`
`list_pyroscope_profile_types`	Pyroscope	列出可用的性能分析类型	`datasources:query`	`datasources:uid:pyroscope-uid`
`query_pyroscope`	Pyroscope	从 Pyroscope 查询性能分析数据、指标或两者	`datasources:query`	`datasources:uid:pyroscope-uid`
`get_assertions`	Asserts	获取给定实体的断言摘要	插件特定权限	插件特定范围
`agento11y_manage_conversations`	Agent Observability*	从 Grafana Agent Observability 列出、搜索和获取 LLM 对话	`grafana-agento11y-app.conversations:read`	不适用
`agento11y_manage_generations`	Agent Observability*	从 Grafana Agent Observability 获取 LLM 生成详情和评估分数	`grafana-agento11y-app.data:read`	不适用
`agento11y_manage_agents`	Agent Observability*	读取代理目录：列出代理、完整获取一个代理版本、列出版本历史以及各版本的分数聚合	`grafana-agento11y-app.data:read`	不适用
`agento11y_manage_evaluators`	Agent Observability*	管理评估器、评估器模板和评审目录（列出、获取、更新插入、分支、测试、删除）	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` 用于变更操作和测试	不适用
`agento11y_manage_eval_rules`	Agent Observability*	管理评估规则和护栏（列出、获取、创建、更新、预览、删除）	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` 用于变更操作和预览	不适用
`agento11y_manage_eval_collections`	Agent Observability*	管理已保存的对话及其分组的集合（列出、获取、保存、创建、更新、删除、添加和移除成员）	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` 用于变更操作	不适用
`ask_assistant`	Assistant*	向 Grafana Assistant 发送提示词并返回完整文本回复（通过 `contextId` 支持多轮对话）	插件特定权限	插件特定范围
`generate_deeplink`	Navigation	为 Grafana 资源生成准确的深层链接 URL	无（只读 URL 生成）	不适用
`get_annotations`	Annotations	使用过滤器获取注释	`annotations:read`	`annotations:*` 或 `annotations:id:123`
`create_annotation`	Annotations	创建新注释（标准或 Graphite 格式）	`annotations:write`	`annotations:*`
`update_annotation`	Annotations	更新注释的特定字段（部分更新）	`annotations:write`	`annotations:*`
`get_annotation_tags`	注释	列出注释标签，支持可选筛选	`annotations:read`	`annotations:*`
`list_snapshots`	快照	列出仪表盘快照，支持可选查询和数量限制筛选	`dashboards:read`	`dashboards:*` 或 `dashboards:uid:abc123`
`get_snapshot`	快照	按快照键获取快照元数据和仪表盘负载	`dashboards:read`	`dashboards:*` 或 `dashboards:uid:abc123`
`create_snapshot`	快照	根据完整仪表盘负载创建仪表盘快照	`dashboards:write`	`dashboards:*` 或 `dashboards:uid:abc123`
`delete_snapshot`	快照	按快照键删除仪表盘快照	`dashboards:write`	`dashboards:*` 或 `dashboards:uid:abc123`
`get_panel_image`	渲染	将存储的仪表盘或面板（或来自仓库分支的预配置预览）渲染为 PNG 图像	`dashboards:read`	`dashboards:uid:abc123`
`list_provisioning_repositories`	预配置	列出预配置仓库（例如 git-sync 源）及其来源 URL、分支、同步状态和健康状况	`provisioning.repositories:read`	N/A
`validate_provisioning_file`	预配置	对预配置仓库中的文件进行试运行应用，并报告准入校验错误	`provisioning.repositories:read`	N/A
* 默认情况下已禁用。将类别添加到 `--enabled-tools` 以启用。

CLI 标志参考

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

传输选项：

-t, --transport：传输类型（stdio、sse 或 streamable-http）- 默认值：stdio
--address：SSE/streamable-http 服务器的主机和端口 - 默认值：localhost:8000
--base-path：SSE/streamable-http 服务器的基本路径
--endpoint-path：streamable-http 服务器的端点路径 - 默认值：/mcp

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

Host/Origin 验证在监听器的每个路由上强制执行——/sse、/mcp、/healthz 和 /metrics——因此 DNS 重绑定浏览器无法访问其中任何一个。Stdio 传输不受影响。

--allowed-hosts：逗号分隔的 Host 头值允许列表。默认为 --address 的回环变体（例如 localhost:8000,127.0.0.1:8000,[::1]:8000）。解析为空的值（未设置、,、, 等）也会回退到默认值，因此拼写错误不会静默禁用检查。带有 Host 头且不在允许列表中的请求将被拒绝，返回 403。传递 * 以禁用检查——仅在运行在可信反向代理（改写 Host）之后或隔离网络中时安全。K8s httpGet 探针和外部 /metrics 抓取将需要在此列表中显式指定主机名、*、或使用 tcpSocket 探针 / 单独的指标端口（--metrics-address）。
--allowed-origins：逗号分隔的 Origin 头值允许列表。默认为空——任何携带 Origin 头的请求都将被拒绝（浏览器总会为跨域请求发送一个，且任何浏览器都不应直接调用此服务器）。设置为显式列表以允许基于浏览器的客户端，或设置为 * 以禁用检查。

调试和日志：

--debug：启用调试模式以进行详细的 HTTP 请求/响应日志记录
--log-level：日志级别（debug、info、warn、error）- 默认值：info

Grafana 客户端选项：

--grafana-timeout：Grafana 客户端发出的请求的时间限制。接受 Go 持续时间字符串（例如 10s、500ms）- 默认值：10s
--include-args-in-spans：在 OpenTelemetry span 中包含工具调用参数。仅在非生产环境或已知参数不包含 PII 时启用 - 默认值：false

可观测性：

--metrics：在 /metrics 启用 Prometheus 指标端点
--metrics-address：指标服务器的单独地址（例如 :9090）。如果为空，指标将在主服务器上提供
--slow-request-threshold：当任何 MCP 请求（工具调用、列表、资源读取等）耗时超过此持续时间时记录事件。接受 Go 持续时间字符串（例如 500ms、5s）。默认值 0 禁用慢请求日志。参见慢请求日志部分。
--slow-request-log-level：慢请求事件的日志级别（info 或 warn）- 默认值：warn。

会话管理：

--session-idle-timeout-minutes：会话空闲超时（分钟）。超过此持续时间无活动的会话将被自动回收 - 默认值：30。设置为 0 以禁用会话回收。仅适用于 SSE 和 streamable-http 传输。

工具配置：

--enabled-tools：逗号分隔的已启用类别列表 - 默认值：除 admin、agento11y、assistant、athena、clickhouse、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 以检测是否存在更多数据）。
--disable-search：禁用搜索工具
--disable-datasource：禁用数据源工具
--disable-incident：禁用事件工具
--disable-prometheus：禁用 prometheus 工具
--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-sift：禁用 sift 工具
--disable-admin：禁用管理工具
--disable-pyroscope：禁用 pyroscope 工具
--disable-navigation：禁用导航工具
--disable-rendering：禁用渲染工具（面板/仪表板图像导出）
--disable-snapshot：禁用快照工具
--disable-cloudwatch：禁用 CloudWatch 工具
--disable-examples：禁用查询示例工具
--disable-clickhouse：禁用 ClickHouse 工具
--disable-snowflake：禁用 Snowflake 工具
--disable-runpanelquery：禁用运行面板查询工具
--disable-graphite：禁用 Graphite 工具
--disable-athena：禁用 Athena 工具
--disable-provisioning：禁用资源配置工具
--disable-agento11y：禁用 Agent Observability 工具
--disable-assistant：禁用 Grafana Assistant 工具

只读模式

--disable-write 标志提供了一种以只读模式运行 MCP 服务器的方法，防止对您的 Grafana 实例进行任何写入操作。这对于需要提供安全的只读访问场景非常有用，例如：

使用权限有限的只读服务账户
为 AI 助手提供可观测性数据而不具备修改能力
在应限制写入访问的生产环境中运行
测试和开发场景中防止意外修改

当启用 --disable-write 时，以下写入操作将被禁用：

仪表板工具：

update_dashboard

文件夹工具：

create_folder

事件工具：

create_incident
add_activity_to_incident

告警工具：

alerting_manage_rules（创建、更新、删除操作）

注解工具：

create_annotation
update_annotation

Sift 工具：

find_error_pattern_logs（创建调查）
find_slow_requests（创建调查）

快照工具：

create_snapshot
delete_snapshot

Agent Observability 工具：

agento11y_manage_evaluators（upsert、delete、fork、test evaluator 操作）
agento11y_manage_eval_rules（创建、更新、删除、预览规则和防护操作）
agento11y_manage_eval_collections（保存和删除已保存的对话；创建、更新、删除集合；添加和移除集合成员）

所有读取操作仍然可用，允许您查询仪表板、运行 PromQL/LogQL 查询、列出资源和检索数据。

客户端 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 内联传递令牌，您还可以将 GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE 指向包含令牌的文件路径。该文件在每次请求时都会重新读取，因此轮换的令牌会自动被获取，无需重启服务器。

这在 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 头： 在使用 SSE 或 streamable HTTP 传输时设置 X-Grafana-Org-Id（头优先于环境变量——这意味着您也可以设置默认组织）。

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

带有组织 ID 的示例：

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

自定义 HTTP 头

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

带有自定义头的示例：

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

转发来自客户端的头（仅限 SSE/Streamable-HTTP）

当 MCP 服务器在负责处理 SSO 的网关或反向代理（例如支持 OIDC 的 AWS ALB）后面运行时，每个用户的会话 cookie 必须到达 Grafana，以便将请求与已认证用户关联。GRAFANA_FORWARD_HEADERS 环境变量通过指定逗号分隔的头名称允许列表来启用此功能，这些头将从传入的 HTTP 请求复制到每个出站的 Grafana API 请求。

这仅适用于使用 SSE（-t sse）或 streamable-http（-t streamable-http）传输时。在 stdio 模式下无效。

示例：转发会话 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 中定义的任何头合并。如果某个头名称同时出现在两者中，则对于该请求，传入请求的值优先。

您有几种安装 mcp-grafana 的选项：
- uvx（推荐）：如果您已安装 uv，则无需额外设置——uvx 将自动下载并运行服务器：
```
uvx mcp-grafana
```

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

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

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 模式：在此模式下，服务器以 HTTP 服务器形式运行，客户端连接到该服务器。您必须使用 -p 标志暴露端口 8000：

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

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

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

对于使用服务器 TLS 证书的 HTTPS streamable HTTP 模式：

docker pull grafana/mcp-grafana
docker run --rm -p 8443:8443 \
  -v /path/to/certs:/certs:ro \
  -e GRAFANA_URL=http://localhost:3000 \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> \
  grafana/mcp-grafana \
  -t streamable-http \
  -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/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 数据源客户端
事件管理（Incident management）客户端
Sift 调查客户端
告警（Alerting）客户端
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)

接入您自己的 HTTP 服务器时的 URL 验证：

当库使用者将 mcp-grafana 的上下文函数接入他们自己的 http.Server 时，请安装 ValidateGrafanaURLMiddleware 以拒绝格式错误的 X-Grafana-URL 头并返回 400 Bad Request（与二进制文件的行为一致）：

mux.Handle(path, mcpgrafana.ValidateGrafanaURLMiddleware(yourMCPHandler))

当直接调用 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)

两种模式都共享 ValidateGrafanaURL 作为唯一的验证器。

服务器 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

这将使 MCP 服务器在 HTTPS 端口 8443 上启动。客户端随后将连接到 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

# With custom address
curl http://localhost:9090/healthz

注意： 健康检查端点仅在使用 SSE 或 streamable HTTP 传输时可用。使用 stdio 传输（-t stdio）时不可用，因为 stdio 不暴露 HTTP 服务器。

可观测性

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`	Histogram	MCP 操作的持续时间（标签：`mcp_method_name`、`gen_ai_tool_name`、`error_type`、`network_transport`、`mcp_protocol_version`）
`mcp_server_session_duration_seconds`	Histogram	MCP 客户端会话的持续时间（标签：`network_transport`、`mcp_protocol_version`）
`http_server_request_duration_seconds`	Histogram	HTTP 服务器请求的持续时间（来自 otelhttp）

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

慢请求日志

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

故障排除

Grafana 版本兼容性

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

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

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

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

开发

欢迎贡献！如果您有任何建议或改进，请提出 issue 或提交 pull request。

本项目使用 Go 编写。请按照您所在平台的说明安装 Go。

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

make run

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

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

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

make build-image

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

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

如果您需要改为以 STDIO 模式运行，请覆盖传输设置：

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

测试

有三种类型的测试可用：

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

make test-unit

您还可以使用以下命令运行单元测试：

make test

集成测试（需要 docker 容器启动并运行）：

make test-integration

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

make test-cloud

注意：云测试在 CI 中自动配置。对于本地开发，您需要设置自己的 Grafana Cloud 实例和凭据。

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

docker-compose up -d

集成测试可以通过以下命令运行：

make test-all

如果您添加更多工具，请为它们添加集成测试。现有测试应该是一个很好的起点。

代码检查

要检查代码，请运行：

make lint

这包括一个自定义 linter，用于检查 jsonschema 结构体标签中未转义的逗号。description 字段中的逗号必须使用 \\, 进行转义，以防止静默截断。您可以仅运行此 linter：

make lint-jsonschema

有关更多详细信息，请参阅 JSONSchema Linter 文档。

许可证

本项目根据 Apache License, Version 2.0 许可证授权。