MCP Grafana

Grafana MCP服务器

    

A. 模型上下文协议 Grafana的MCP服务器。

这提供了对Grafana实例和周围生态系统的访问。

快速开始

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

{
  "mcpServers": {
    "grafana": {
      "command": "uvx",
      "args": ["mcp-grafana"],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_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数据源执行PromQL查询（支持即时和范围度量查询）。
• 查询Prometheus元数据： 从Prometheus数据源检索度量元数据、度量名称、标签名称和标签值。
• 查询直方图百分位数： 使用histogram_quantile计算直方图百分位值（p50、p90、p95、p99）。

洛基查询

• 查询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 致你的 --enabled-tools 旗帜。

• 查询石墨： 针对Graphite数据源执行Graphite渲染API查询。
• 列出石墨指标： 浏览和发现Graphite度量路径。
• 列出Graphite标签： 列出可用的Graphite标记和标记值。
• 查询石墨密度： 查询给定图案的石墨度量密度。

雅典娜查询

注： 雅典娜工具 默认情况下禁用。要启用它们，请添加 athena 致你的 --enabled-tools 旗帜。

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

雪花查询

注： 雪花工具 默认情况下禁用。要启用它们，请添加 snowflake 致你的 --enabled-tools 旗帜。

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

• 列出雪花表： 通过以下方式发现表（包括数据库、模式、类型、行数和大小） INFORMATION_SCHEMA.TABLES。可选数据库/架构筛选器。
• 描述表架构： 获取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、源字段和可选相关性得分。

事件

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

筛选调查

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

告警

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

Grafana OnCall

• 列出并管理时间表： 在Grafana OnCall中查看和管理随叫随到时间表。
• 获取班次详细信息： 检索有关特定随叫随到轮班的详细信息。
• 获取当前随叫随到的用户： 查看哪些用户当前处于待命状态以获取日程安排。
• 列出团队和用户： 查看所有OnCall团队和用户。
• 列出警报组： 根据各种条件（包括状态、集成、标签和时间范围）查看和筛选Grafana OnCall中的警报组。
• 获取警报组详细信息： 按ID检索特定警报组的详细信息。

管理员

注： 管理工具包括 默认情况下禁用。要启用它们，请包括 admin 在你的 --enabled-tools 旗帜。

• 列出团队： 查看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编码数据返回，以用于报告、警报或演示文稿。支持自定义维度、时间范围、主题、比例和仪表板变量。

- _注意：需要 Grafana图像渲染器 要安装和配置的服务。_

工具列表是可配置的，因此您可以选择要向MCP客户端提供哪些工具。 如果你不使用某些功能，或者你不想占用太多的上下文窗口，这很有用。 要禁用某类工具，请使用 --disable- 启动服务器时标记。例如，要禁用 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)

工具

_\*默认情况下禁用。将类别添加到 --enabled-tools 以启用。_

CLI标志参考

这 mcp-grafana binary支持各种命令行标志进行配置：

运输选项：

• -t, --transport：运输类型(stdio, sse，或 streamable-http)-默认值： stdio
• --address：SSE/流式http服务器的主机和端口-默认值： localhost:8000
• --base-path：SSE/可流式传输http服务器的基本路径
• --endpoint-path：可流式传输http服务器的终结点路径-默认值： /

调试和日志记录：

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

可观察性：

• --metrics：在以下位置启用Prometheus指标端点 /metrics
• --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和可流式传输的http。

工具配置：

• --enabled-tools：逗号分隔的已启用类别列表-默认值：除以下类别外的所有类别 admin, athena, clickhouse, cloudwatch, elasticsearch, examples, graphite, runpanelquery，以及 snowflake为了启用禁用类别，将它们添加到列表中（例如。， "search,datasource,...,snowflake")
• --max-loki-log-limit：每个返回的最大日志行数 query_loki_logs call-默认值： 100注意：在Loki的服务器端至少设置1 max_entries_limit_per_query 允许截断检测（工具请求 limit+1 内部检测是否存在更多数据）。
• --disable-search：禁用搜索工具
• --disable-datasource：禁用数据源工具
• --disable-incident：禁用事件工具
• --disable-prometheus：禁用普罗米修斯工具
• --disable-write：禁用写入工具（创建/更新操作）
• --disable-loki：禁用loki工具
• --disable-elasticsearch：禁用弹性搜索和打开搜索工具
• --disable-influxdb：禁用InfluxDB工具
• --disable-alerting：禁用警报工具
• --disable-dashboard：禁用仪表板工具
• --disable-oncall：禁用oncall工具
• --disable-asserts：禁用断言工具
• --disable-sift：禁用筛选工具
• --disable-admin：禁用管理工具
• --disable-pyroscope：禁用检流计工具
• --disable-navigation：禁用导航工具
• --disable-rendering：禁用渲染工具（面板/仪表板图像导出）
• --disable-cloudwatch：禁用CloudWatch工具
• --disable-examples：禁用查询示例工具
• --disable-clickhouse：禁用ClickHouse工具
• --disable-snowflake：禁用雪花工具
• --disable-runpanelquery：禁用运行面板查询工具
• --disable-graphite：禁用Graphite工具
• --disable-athena：禁用Athena工具

只读模式

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

• 使用只读权限有限的服务帐户
• 为AI助手提供可观察性数据，无需修改功能
• 在应限制写访问的生产环境中运行
• 您希望防止意外修改的测试和开发场景

当 --disable-write 如果启用，则禁用以下写入操作：

仪表板工具：

• update_dashboard

文件夹工具：

• create_folder

事件工具：

• create_incident
• add_activity_to_incident

警报工具：

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

注释工具：

• create_annotation
• update_annotation

筛选工具：

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

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

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

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

服务器TLS配置（仅限流式http传输）：

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

用法

此MCP服务器可与本地Grafana实例和Grafana Cloud一起使用。对于Grafana Cloud，请使用您的实例URL（例如。， https://myinstance.grafana.net)而不是 http://localhost:3000 在下面的配置示例中。

1. 如果使用服务帐户令牌身份验证，请在Grafana中创建一个具有足够权限的服务帐户，以使用您要使用的工具，

生成服务帐户令牌，并将其复制到剪贴板以在配置文件中使用。 跟随 Grafana服务帐户文档 有关创建服务帐户令牌的详细信息。 提示：如果您不习惯配置细粒度RBAC作用域，一个更简单（但限制较少）的选项是分配内置 Editor 将角色添加到服务帐户。这授予了涵盖大多数MCP服务器操作的广泛读/写访问权限——当便利性超过严格的最低权限要求时使用它。

> 注： 环境变量 GRAFANA_API_KEY 已弃用，将在未来版本中删除。请迁移到使用 GRAFANA_SERVICE_ACCOUNT_TOKEN 相反。旧的变量名将继续用于向后兼容性，但会显示弃用警告。

多组织支持

您可以使用以下任一方式指定要与哪个组织交互：

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

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

组织ID示例：

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

自定义HTTP标头

您可以使用 GRAFANA_EXTRA_HEADERS 环境变量。该值应该是一个JSON对象，将标头名称映射到值。

自定义标题示例：

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

从客户端转发标头（仅限SSE/流式HTTP）

当MCP服务器在处理SSO的网关或反向代理（例如带有OIDC的AWS ALB）后面运行时，每个用户的会话cookie必须到达Grafana，以便它可以将请求与经过身份验证的用户相关联。这 GRAFANA_FORWARD_HEADERS 环境变量通过指定要从中复制的逗号分隔的标头名称列表来实现这一点 传入的 对每个出站Grafana API请求的HTTP请求。

这仅适用于使用SSE时(-t sse)或可流式传输的http(-t streamable-http)运输。它在stdio模式下无效。

示例：转发会话cookie

{
  "env": {
    "GRAFANA_URL": "https://grafana.internal",
    "GRAFANA_SERVICE_ACCOUNT_TOKEN": "",
    "GRAFANA_FORWARD_HEADERS": "Cookie"
  }
}

您可以通过用逗号分隔来转发多个标题：

GRAFANA_FORWARD_HEADERS=Cookie,X-Session-Id

转发的标头将与中定义的任何标头合并 GRAFANA_EXTRA_HEADERS。如果两者中都出现标头名称，则传入请求中的值对该请求具有优先权。

1. 您有几个安装选项 mcp-grafana:

- uvx（推荐）：如果你有 紫外线 已安装，无需额外设置-- uvx 将自动下载并运行服务器：

     uvx mcp-grafana

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

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

1. STDIO模式：对于stdio模式，您必须用以下命令显式覆盖默认值 -t stdio 并包括 -i 用于保持stdin打开的标志：

     docker pull grafana/mcp-grafana
     # For local Grafana:
     docker run --rm -i -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN= grafana/mcp-grafana -t stdio
     # For Grafana Cloud:
     docker run --rm -i -e GRAFANA_URL=https://myinstance.grafana.net -e GRAFANA_SERVICE_ACCOUNT_TOKEN= grafana/mcp-grafana -t stdio

2. SSE模式：在此模式下，服务器作为客户端连接的HTTP服务器运行。您必须使用 -p 标志：

     docker pull grafana/mcp-grafana
     docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN= grafana/mcp-grafana

3. 流式HTTP模式：在这种模式下，服务器作为一个独立的进程运行，可以处理多个客户端连接。您必须使用 -p flag：对于此模式，您必须使用以下命令显式覆盖默认值 -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= 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= \
       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= --set grafana.url= my-release grafana/grafana-mcp

1. 将服务器配置添加到客户端配置文件中。例如，对于Claude Desktop：

如果使用uvx：

   {
     "mcpServers": {
       "grafana": {
         "command": "uvx",
         "args": ["mcp-grafana"],
         "env": {
           "GRAFANA_URL": "http://localhost:3000",
           "GRAFANA_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": "",
           // If using username/password authentication
           "GRAFANA_USERNAME": "",
           "GRAFANA_PASSWORD": "",
           // Optional: specify organization ID for multi-org support
           "GRAFANA_ORG_ID": "1"
         }
       }
     }
   }

注意：如果你看到 Error: spawn mcp-grafana ENOENT 在Claude Desktop中，您需要指定以下内容的完整路径 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": "",
        // If using username/password authentication
        "GRAFANA_USERNAME": "",
        "GRAFANA_PASSWORD": "",
        // Optional: specify organization ID for multi-org support
        "GRAFANA_ORG_ID": "1"
      }
    }
  }
}

注： -t stdio 这个参数在这里很重要，因为它覆盖了Docker镜像中的默认SSE模式。

在远程MCP服务器上使用VSCode

如果您使用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"
    }
  }
}

调试模式

您可以通过添加以下命令为Grafana传输启用调试模式 -debug 标志到命令。这将提供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": ""
      }
    }
  }
}

如果使用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": ""
      }
    }
  }
}

注：与标准配置一样 -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": ""
      }
    }
  }
}

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": ""
      }
    }
  }
}

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

• Grafana OpenAPI的主要客户端
• Prometheus数据源客户端
• Loki数据源客户端
• 事件管理客户端
• 筛选调查客户
• 提醒客户
• 断言客户

直接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，以避免可访问的恐慌：

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= \
  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指标、OpenTetry分布式跟踪和OpenTetry日志导出，遵循 OTel MCP语义约定.跟踪和日志导出通过标准配置 OTEL_* 环境变量，适用于任何传输。

注： mcp-grafana目前仅支持跟踪和日志的OTLP/gRPC传输。 OTEL_EXPORTER_OTLP_PROTOCOL （及其 _TRACES_PROTOCOL / _LOGS_PROTOCOL 变体）不受尊重——不管怎样，都使用gRPC。

指标

使用SSE或流式HTTP传输时，使用 --metrics 标志：

# 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

可用指标：

注： 仅当使用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

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

慢速请求日志记录适用于所有传输（包括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 )并包括以下属性 gen_ai.tool.name, mcp.method.name，以及 mcp.session.id服务器还支持W3C跟踪上下文从 _meta 工具调用请求字段。

日志

当 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传输下导出，这使得从本地集中日志变得容易 mcp-grafana IDE客户端调用的实例。

带有度量、跟踪和日志的Docker示例：

docker run --rm -p 8000:8000 \
  -e GRAFANA_URL=http://localhost:3000 \
  -e GRAFANA_SERVICE_ACCOUNT_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或更高版本以解决此问题。

发展

欢迎投稿！如果您有任何建议或改进，请打开问题或提交拉取请求。

这个项目是用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

测试

有三种类型的测试可供选择：

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

make test-unit

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

make test

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

make test-integration

1. 云测试（需要云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许可证，版本2.0.