Grafana

官方

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

GitHub

3.5k

试用此 MCP赞助

你可以用 Grafana MCP 做什么？

搜索和检查仪表板 — 按标题、文件夹、标签或星标状态查找仪表板，然后提取摘要或特定的 JSONPath 属性，以尽量减少上下文占用。
查询可观测性数据 — 直接对已配置的数据源运行 PromQL、LogQL、SQL、CloudWatch、Graphite、Elasticsearch 或 InfluxDB 查询。
管理告警和事件 — 创建、更新和删除告警规则，查看触发状态，并管理 Grafana Incident 记录，包括自定义字段。
渲染仪表板图像 — 生成面板或整个仪表板的 PNG 快照，支持自定义时间范围、主题和尺寸，用于报告或告警。
生成准确的深度链接 — 创建指向仪表板、面板或 Explore 视图的直接 URL，并附带正确的时间范围和参数，而不是猜测 URL。
管理注释和快照 — 创建、更新、修补或删除注释，并列出或创建带有过期选项的仪表板快照。

文档

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），请参阅 Usage。

要求

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

功能

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

仪表盘

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

运行面板查询

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

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

上下文窗口管理

仪表盘工具现在包含多种策略来有效管理上下文窗口使用（issue #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 参数显式设置。

SQL 数据源查询

注意： SQL 工具默认禁用。要启用它们，请将 sql 添加到您的 --enabled-tools 标志中。向后兼容别名 clickhouse、snowflake 和 athena 也可用。

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

列出数据库/模式/目录： 发现 SQL 数据源的组织单元。对于 Athena，省略目录以列出目录，或传递目录以列出数据库。
列出表： 列出数据库或模式中的表及其元数据（行数、大小（如果可用））。
描述表模式： 获取列名、类型、可空性、默认值和注释。
查询 SQL： 使用数据源特定的宏替换（$__timeFilter(col)、$__from/$__to、$__interval、${varname}）、自动限制执行和模板变量支持执行 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 指标密度。

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、源字段和可选的相关性分数。

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 标志中。

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

事件（Incidents）

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

Sift 调查

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

告警（Alerting）

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

Grafana OnCall

列出和管理排班： 查看和管理 Grafana OnCall 中的值班排班。
获取轮班详情： 检索特定值班轮班的详细信息。
获取当前值班用户： 查看当前在某个排班中值班的用户。
列出团队和用户： 查看所有 OnCall 团队和用户。
列出告警组： 按各种条件（包括状态、集成、标签和时间范围）查看和筛选 Grafana OnCall 中的告警组。
获取告警组详情： 通过 ID 检索特定告警组的详细信息。

管理（Admin）

注意： 管理工具默认禁用。要启用它们，请在 --enabled-tools 标志中包含 admin。

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

用户（User）

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

导航（Navigation）

生成深度链接： 为 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?schemaVersion=1&panes={"a":{"datasource":"prometheus-uid"}}）。低于 10.2 的 Grafana 无法理解 panes，因此对于这些版本会输出旧版 ?left={...} 格式。
- 时间范围支持： 向链接添加时间范围参数（from=now-1h&to=now）
- 自定义参数： 包含其他查询参数，如仪表板变量或刷新间隔

注释（Annotations）

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

快照（Snapshots）

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

渲染（Rendering）

获取面板或仪表板图像： 将 Grafana 仪表板面板或完整仪表板渲染为 PNG 图像。返回 base64 编码的图像数据，用于报告、告警或演示。支持自定义尺寸、时间范围、主题、缩放比例和仪表板变量。还支持通过可选的 provisioningPreview 参数，从配置仓库分支（例如 git-sync PR 预览）渲染尚未应用的仪表板。
- 注意：需要安装并配置 Grafana Image Renderer 服务。

配置管理（Provisioning）

列出配置仓库： 列出为此 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`	管理	列出所有团队	`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:*`
`user_info`	用户	当前身份、能力和可访问的组织	无（已登录用户）	—
`search_dashboards`	搜索	按查询、文件夹 UID、标签或星标搜索仪表盘	`dashboards:read`	`dashboards:*` 或 `dashboards:uid:abc123`
`get_dashboard_by_uid`	仪表盘	按 uid 获取仪表盘，可选指定已保存版本	`dashboards:read`	`dashboards:uid:abc123`
`list_dashboard_versions`	仪表盘	列出仪表盘的已保存版本（版本、作者、时间、消息）	`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`	运行面板查询*	执行一个或多个仪表盘面板查询	`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 中的事件添加活动项	编辑者角色	不适用
`update_incident`	事件	更新 Grafana Incident 中的事件（状态、严重性、标题或自定义字段）	编辑者角色	不适用
`get_incident`	事件	按 ID 获取单个事件，包括其自定义字段	查看者角色	不适用
`list_incident_custom_fields`	事件	列出为事件配置的自定义字段，包括其类型和选择选项	查看者角色	不适用
`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_sql_databases`	SQL*	列出 SQL 数据源中的数据库、模式或目录	`datasources:query`	`datasources:uid:*`
`list_sql_tables`	SQL*	列出 SQL 数据源中的表	`datasources:query`	`datasources:uid:*`
`describe_sql_table`	SQL*	获取表的列模式	`datasources:query`	`datasources:uid:*`
`query_sql`	SQL*	使用宏替换执行 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:*`
`list_cloudwatch_dimension_values`	CloudWatch*	列出维度键的值	`datasources:query`	`datasources:uid:*`
`query_cloudwatch`	CloudWatch*	执行 CloudWatch 指标查询	`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`
`alerting_manage_rules`	Alerting	管理告警规则（列出、获取、版本、创建、更新、删除）	`alert.rules:read` + `alert.rules:write` 用于变更	`folders:*` 或 `folders:uid:alerts-folder`
`alerting_manage_routing`	Alerting	管理通知策略、联系点和时间间隔	`alert.notifications:read`	全局范围
`alerting_manage_silences`	Alerting	管理告警静默（列出、获取、创建、更新、过期）	`alert.instances:read` + `alert.instances:write` 用于变更	全局范围
`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`	插件特定范围
`update_alert_group`	OnCall	确认、取消确认、解决或取消解决告警组	`grafana-oncall-app.alert-groups:write`（和 `: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` 用于变更	不适用
`agento11y_manage_experiments`	Agent Observability*	读取离线实验、其试验、分数、工件元数据和过滤方面；更新和取消实验	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` 用于变更	不适用
`agento11y_manage_test_suites`	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:read`	`annotations:*` 或 `annotations:id:123`
`create_annotation`	注解	创建新注解（标准格式或 Graphite 格式）	`annotations:write`	`annotations:*`
`update_annotation`	注解	更新注解的特定字段（部分更新）	`annotations:write`	`annotations:*`
`delete_annotation`	注解	按 ID 删除注解	`annotations:delete`	`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`	不适用
`search_docs`	文档	搜索 Grafana 文档或列出产品组（省略查询以列出产品）	无（公开的 grafana.com/docs）	不适用
`get_doc`	文档	获取文档页面；设置 outline_only 以获取标题，或设置 section 以进行有界检索	无（公开的 grafana.com/docs）	不适用
* 默认禁用。将类别添加到 `--enabled-tools` 以启用。

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
--server-name：MCP 握手和 OTel service.name 中使用的服务器名称 — 默认值：mcp-grafana。覆盖 GRAFANA_MCP_SERVER_NAME 环境变量
--instructions-append：附加到初始化时返回给 MCP 客户端的服务器指令的文本，以便每个连接的代理都能看到它

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 标头的请求都会被拒绝（浏览器总是为跨源请求发送一个，并且没有浏览器应该直接调用此服务器）。设置为显式列表以允许基于浏览器的客户端，或设置为 * 以禁用检查。

调用方身份验证（仅限 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 组合。

调试和日志记录：

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

Grafana 客户端选项：

--grafana-timeout：Grafana 客户端发出的请求的时间限制。接受 Go 持续时间字符串（例如 10s、500ms）— 默认值：10s
--include-args-in-spans：在 OpenTelemetry 跨度中包含工具调用参数。仅在非生产环境或已知参数不包含 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；任何无法识别的值都会禁用报告。请参阅匿名使用统计部分。

会话管理：

--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 以检测是否存在更多数据）。
--loki-guardrail-mode：query_loki_logs 的 Loki 查询成本护栏 — 默认值：off。Loki 不会在没有行过滤器的情况下对日志查询强制执行 max_query_bytes_read，因此宽范围上的宽选择器可以扫描 TB 级数据；护栏要求选择性的流选择器，限制有效时间范围（包括范围向量持续时间，如 [30d]），并在运行查询之前预先检查 Loki 的索引/统计字节估计。shadow 记录将被阻止的查询但允许它们运行（它仍然支付索引/统计往返费用）；enforce 以 LLM 可以操作的改写指导拒绝它们。在 VictoriaLogs 上，护栏仅适用于选择器形状（{...}）查询 — 当没有选择器解析（通常的无花括号 LogsQL 形状）时，查询完全通过，字节预算检查永远不会应用（没有廉价的索引估计）。环境变量回退：GRAFANA_LOKI_GUARDRAIL_MODE。
--loki-guardrail-max-bytes：单个 query_loki_logs 调用可能扫描的最大字节数，通过 Loki 的索引/统计 API 估计 — 默认值：107374182400（100 GiB）。0 禁用字节预算检查。环境变量回退：GRAFANA_LOKI_GUARDRAIL_MAX_BYTES。
--loki-guardrail-max-range：单个 query_loki_logs 调用的最大有效时间范围，包括范围向量持续时间 — 默认值：24h。接受 Go 持续时间字符串。0 禁用范围检查。环境变量回退：GRAFANA_LOKI_GUARDRAIL_MAX_RANGE。
--loki-enforced-matchers：AND 到每个原生 Loki 查询中的 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 下也保持注册的单个工具名称逗号分隔列表，用于写入行为足够限定以独立选择加入的工具（例如 find_error_pattern_logs,find_slow_requests）。对通过例如 --disable-sift 禁用整个类别的工具没有影响。
--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-sql：禁用 SQL 数据源工具（ClickHouse、Snowflake、Athena、MySQL、PostgreSQL、MSSQL）。别名 --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_manage_rules（创建、更新、删除操作）
alerting_manage_silences（创建、更新、删除操作）

OnCall 工具：

update_alert_group

注释工具：

create_annotation
update_annotation
delete_annotation Sift 工具：
find_error_pattern_logs（创建调查）
find_slow_requests（创建调查）

这些工具仅通过 Sift API 创建临时的 Sift 调查记录——它们从不触碰 Grafana 仪表盘、警报或数据源。没有它们，list_sift_investigations/get_sift_investigation/get_sift_analysis 就没有可列出或获取的内容。传递 --enable-write-tools=find_error_pattern_logs,find_slow_requests 以在 --disable-write 下保持它们的注册。

快照工具：

create_snapshot
delete_snapshot

原始 SQL 查询工具：

这些工具会执行您提供的任何查询而不进行检查，因此当数据源凭据允许时，它们可以进行写入操作——query_sql 将运行 DROP TABLE，query_influxdb 将运行 DELETE。因此，只读模式会移除它们。当已知数据源凭据为只读时，传递 --enable-query 以保留它们。

query_sql
query_influxdb

Agent 可观测性工具：

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

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

无查询模式

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

它是三种查询设置中最强的，并且优先于 --enable-query：

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

当启用 --disable-query 时，以下工具不会被注册：

Prometheus 工具：

query_prometheus
query_prometheus_histogram

Loki 工具：

query_loki_logs
query_loki_patterns

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

Elasticsearch/OpenSearch 和 Quickwit 工具：

query_elasticsearch
query_quickwit

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

query_influxdb

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

query_sql

Graphite 工具：

query_graphite
query_graphite_density

CloudWatch 工具：

query_cloudwatch

Pyroscope 工具：

query_pyroscope

运行面板查询工具：

run_panel_query

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

请注意，--disable-query 控制查询工具和 grafana_api_request POST 到 /api/ds/query 的路径，但不会监管通往数据源的每条路由。在只读模式下，grafana_api_request 仅在启用查询工具时允许 POST 到 /api/ds/query（与原始 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 内联传递令牌，也可以将 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 标头，确保操作在指定的组织上下文中执行。

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

上述选项为整个连接固定了组织。要让单个连接在每次工具调用时针对不同组织，请使用 --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 流量。

从客户端转发标头（仅限 SSE/Streamable-HTTP）

当 MCP 服务器在网关或反向代理（例如带有 OIDC 的 AWS ALB）后面运行并处理 SSO 时，每个用户的会话 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 中定义的任何标头合并。如果标头名称同时出现在两者中，则传入请求的值优先用于该请求。

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

您有几种安装 mcp-grafana 的选项：
- uvx（推荐）：如果您已安装 uv，则无需额外设置——uvx 将自动下载并运行服务器：
```
uvx mcp-grafana
```
- Docker 镜像：使用 Docker Hub 上的预构建 Docker 镜像。
  
  重要：Docker 镜像的入口点默认配置为以 SSE 模式运行 MCP 服务器，但大多数用户希望使用 STDIO 模式以直接集成到 AI 助手（如 Claude Desktop）：
  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 模式不受影响。请参阅调用者认证。

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

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

下载二进制文件：从 releases page 下载 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)

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 配置（仅限流式 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

# 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 或流式 HTTP 传输时可用。使用 stdio 传输（-t stdio）时不可用，因为 stdio 不暴露 HTTP 服务器。

匿名使用统计

服务器可以向 Grafana Labs 报告关于自身的匿名使用统计：调用了哪些工具、这些调用中有多少失败，以及服务器如何配置。一份报告涵盖一个服务器进程——而不是一个用户或一个对话——每 4 小时发送一次，并在关闭时再发送一次。此版本默认禁用报告——接收端点尚未上线——后续版本将把默认值更改为启用，并提供相同的退出选项。

工具参数、资源名称、查询、日志行、错误消息和凭据永远不会被发送。标志仅按名称记录，从不按值记录，Grafana 实例仅描述为 cloud 或 self_hosted——从不通过 URL、主机名、堆栈 slug 或组织。没有任何内容是按用户、按会话或按客户端的：线上没有会话标识符，也没有办法将工具调用归属于特定客户端。

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

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

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

DO_NOT_TRACK=1 也会禁用报告，遵循跨工具的 DO_NOT_TRACK 约定。只有 1 有任何效果，它只能禁用，而 --usage-stats 和 GRAFANA_USAGE_STATS 都会覆盖它，因此全局设置它的主机仍然可以选择让一个服务器重新启用。

GRAFANA_USAGE_STATS_ENDPOINT 更改目的地。它不是退出选项。

有关完整字段列表、永远不会发送的内容、如何读取数据及其限制，请参阅 Anonymous usage statistics。

可观测性

MCP 服务器支持 Prometheus 指标、OpenTelemetry 分布式追踪和 OpenTelemetry 日志导出，遵循 OTel MCP semantic conventions。追踪和日志导出通过标准 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 传输不可用。

当 Loki cost guardrail（--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 推出期间如何读取它们，请参阅 Observability。

库嵌入者应设置 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

工具调用跨度遵循 semconv 命名（tools/call <tool_name>），并包含诸如 gen_ai.tool.name、mcp.method.name 和 mcp.session.id 之类的属性。服务器还支持从工具调用请求的 _meta 字段进行 W3C 追踪上下文传播。

日志

当设置了 OTEL_EXPORTER_OTLP_ENDPOINT（或信号特定的 OTEL_EXPORTER_OTLP_LOGS_ENDPOINT）时，服务器除了现有的纯文本 stderr 输出外，还会通过 OTLP/gRPC 导出结构化日志。otelslog 桥接器会自动附加活动 span 中的 trace_id 和 span_id，因此日志记录与服务器已发出的追踪相关联。

追踪和日志独立解析其端点，因此两种信号可以分别启用：仅设置 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT 可启用追踪而无需日志导出，仅设置 OTEL_EXPORTER_OTLP_LOGS_ENDPOINT 可启用日志导出而无需追踪，而通用的 OTEL_EXPORTER_OTLP_ENDPOINT 则同时启用两者。

如果您使用通用的 OTEL_EXPORTER_OTLP_ENDPOINT 但希望禁用日志导出（例如，您的后端不支持 LogsService），请设置：

OTEL_LOGS_EXPORTER=none

这将阻止服务器创建 OTLP 日志导出器，无论端点配置如何，从而避免出现类似 unknown service opentelemetry.proto.collector.logs.v1.LogsService 的错误。

启用 OTLP 日志记录时，stderr 日志记录保持不变；您可以继续依赖容器日志或将 stderr 管道传输到 /dev/null（如果您更喜欢）。

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

传输方式为 OTLP/gRPC（默认端口 4317）。日志可以直接发送到任何接受 OTLP/gRPC 的托管后端——例如 Grafana Cloud——方法是将 OTEL_EXPORTER_OTLP_LOGS_ENDPOINT（或通用的 OTEL_EXPORTER_OTLP_ENDPOINT）指向远程 gRPC 端点，并通过 OTEL_EXPORTER_OTLP_LOGS_HEADERS（或 OTEL_EXPORTER_OTLP_HEADERS）提供认证，与上面的追踪示例类似。本地 OTel 收集器是可选的——对于扇出、批处理或多后端路由很有用，但不是必需的。

信号特定的变体 OTEL_EXPORTER_OTLP_LOGS_ENDPOINT、OTEL_EXPORTER_OTLP_LOGS_HEADERS、OTEL_EXPORTER_OTLP_LOGS_INSECURE、OTEL_EXPORTER_OTLP_LOGS_CERTIFICATE、OTEL_EXPORTER_OTLP_LOGS_TIMEOUT 和 OTEL_EXPORTER_OTLP_LOGS_COMPRESSION 会被优先考虑，并覆盖其通用的 OTEL_EXPORTER_OTLP_* 对应项——请参阅 OTel 导出器规范获取完整列表和优先级规则。

如果配置的收集器不可达，日志记录会在内存中缓冲（默认队列：2048），一旦队列填满，最旧的记录将被丢弃。进程继续运行，不会阻塞服务。如果您需要在中断期间实现无损缓冲，请配置本地 OTel 收集器。

日志也会在 stdio 传输下导出，这使得从 IDE 客户端调用的本地 mcp-grafana 实例集中管理日志变得容易。

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

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

Loki 查询强制

--loki-enforced-matchers 允许操作员限制服务器可以读取的 Loki 日志流，方法是将一组固定的 LogQL 标签匹配器 AND 到服务器发出的每个原生 Loki 查询中。当数据源包含不得暴露的流（例如可能携带敏感信息的日志）但您无法在 Grafana 或 Loki 层限制访问时（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-sift — Sift 调查在服务器端跨所有流分析 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 编写。请按照您平台的说明安装 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 许可证，版本 2.0 授权。