Grafana MCP Server

官方

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

GitHub

3.2k

文档

Grafana MCP 服务器

一个用于 Grafana 的模型上下文协议 (MCP) 服务器。

它提供对您的 Grafana 实例及周边生态系统的访问。

快速开始

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

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

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

要求

Grafana 9.0 或更高版本是完整功能所必需的。某些功能，特别是与数据源相关的操作，可能因缺少 API 端点而无法在早期版本中正常工作。

功能

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

仪表板

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

运行面板查询

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

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

上下文窗口管理

仪表板工具现在包含几种有效管理上下文窗口使用情况的策略（issue #101）：

使用 get_dashboard_summary 进行仪表板概览和规划修改
当您只需要仪表板的特定部分时，使用带有 JSONPath 的 get_dashboard_property
避免使用 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 渲染 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 企业插件 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 查询 DSL 针对 Elasticsearch 或 OpenSearch 数据源执行搜索查询。支持按时间范围过滤以及检索日志、指标或任何索引数据。返回包含索引、ID、源字段和可选相关性评分的文档。

Quickwit 查询

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

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

事件

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

Sift 调查

列出 Sift 调查： 检索 Sift 调查列表，支持限制参数。
获取 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 源），返回每个仓库的标识符及其源 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 权限：

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

有关 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`	管理	列出组织中的所有用户	`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`	`roles:uid:editor`
`list_user_roles`	管理	列出用户的角色	`roles:read`	`global.users:id:123`
`list_team_roles`	管理	列出团队的角色	`roles:read`	`teams:id:7`
`get_resource_permissions`	管理	列出资源的权限	`permissions:read`	`dashboards:uid:abcd1234`
`get_resource_description`	管理	描述 Grafana 资源类型	`permissions:read`	`dashboards:*`
`search_dashboards`	搜索	搜索仪表板	`dashboards:read`	`dashboards:*` 或 `dashboards:uid:abc123`
`get_dashboard_by_uid`	仪表板	通过 uid 获取仪表板	`dashboards:read`	`dashboards:uid:abc123`
`update_dashboard`	仪表板	更新或创建新的仪表板	`dashboards:create`、`dashboards:write`	`dashboards:`、`folders:` 或 `folders:uid:xyz789`
`get_dashboard_panel_queries`	仪表板	从仪表板获取面板标题、查询、数据源 UID 和类型	`dashboards:read`	`dashboards:uid:abc123`
`run_panel_query`	RunPanelQuery*	执行一个或多个仪表板面板查询	`dashboards:read`、`datasources:query`	`dashboards:uid:`、`datasources:uid:`
`get_dashboard_property`	仪表板	使用 JSONPath 表达式提取仪表板的特定部分	`dashboards:read`	`dashboards:uid:abc123`
`get_dashboard_summary`	仪表板	获取仪表板的紧凑摘要（不含完整 JSON）	`dashboards:read`	`dashboards:uid:abc123`
`list_datasources`	数据源	列出数据源	`datasources:read`	`datasources:*`
`get_datasource`	数据源	通过 UID 或名称获取数据源	`datasources:read`	`datasources:uid:prometheus-uid`
`get_query_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`	事件	列出 Grafana Incident 中的事件	查看者角色	不适用
`create_incident`	事件	在 Grafana Incident 中创建事件	编辑者角色	不适用
`add_activity_to_incident`	事件	向 Grafana Incident 中的事件添加活动项	编辑者角色	不适用
`get_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`	配置	生成强制执行已批准标签的 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 语法或 Query DSL 查询 Elasticsearch 或 OpenSearch	`datasources:query`	`datasources:uid:datasource-uid`
`query_quickwit`	Quickwit*	使用 Lucene 语法或 Query 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`	告警	管理告警规则（列出、获取、版本、创建、更新、删除）	`alert.rules:read` + `alert.rules:write`（用于变更）	`folders:*` 或 `folders:uid:alerts-folder`
`alerting_manage_routing`	告警	管理通知策略、联系点和时间间隔	`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	获取给定实体的断言摘要	插件特定权限	插件特定范围
`generate_deeplink`	导航	为 Grafana 资源生成准确的深层链接 URL	无（只读 URL 生成）	不适用
`get_annotations`	注释	使用筛选器获取注释	`annotations:read`	`annotations:*` 或 `annotations:id:123`
`create_annotation`	注释	创建新注释（标准或 Graphite 格式）	`annotations:write`	`annotations:*`
`update_annotation`	注释	更新注释的特定字段（部分更新）	`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`	不适用
`validate_provisioning_file`	配置管理	从配置仓库中试运行应用一个文件，并报告准入验证错误	`provisioning.repositories:read`	不适用
* 默认禁用。将类别添加到 `--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 服务器的端点路径 - 默认值：/

调试与日志：

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

可观测性：

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

所有读取操作仍然可用，允许您查询仪表板、运行 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_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 头： 在使用 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 模式以直接与 AI 助手（如 Claude Desktop）集成：

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 可流式 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 数据源客户端
事件管理客户端
Sift 调查客户端
告警客户端
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 配置（仅限可流式 HTTP 传输）

使用可流式 HTTP 传输（-t streamable-http）时，您可以配置 MCP 服务器提供 HTTPS 而非 HTTP 服务。当您需要保护 MCP 客户端与服务器本身之间的连接时，这非常有用。

服务器为可流式 HTTP 传输支持以下 TLS 配置选项：

--server.tls-cert-file：服务器 HTTPS 的 TLS 证书文件路径（TLS 必需）
--server.tls-key-file：服务器 HTTPS 的 TLS 私钥文件路径（TLS 必需）

注意：这些标志与上面记录的客户端 TLS 标志完全独立。客户端 TLS 标志配置 MCP 服务器如何连接到 Grafana，而这些服务器 TLS 标志配置在使用可流式 HTTP 传输时客户端如何连接到 MCP 服务器。

HTTPS 可流式 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）或可流式 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 或可流式 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 或可流式 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`）
`mcp_server_session_duration_seconds`	直方图	MCP 客户端会话持续时间（标签：`network_transport`、`mcp_protocol_version`）
`http_server_request_duration_seconds`	直方图	HTTP 服务器请求持续时间（来自 otelhttp）

注意： 指标仅在使用 SSE 或可流式 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 后，服务器通过 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

工具调用跨度遵循 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 桥自动附加活动跨度的 trace_id 和 span_id，因此日志记录与服务器已发出的追踪相关联。

启用 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"}

这通常表示您使用的 Grafana 版本早于 9.0。/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

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

make lint-jsonschema

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

许可证

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