grafana/mcp-grafana

# Grafana MCP 服务器 [](https://github.com/grafana/mcp-grafana/actions/workflows/unit.yml) [](https://github.com/grafana/mcp-grafana/actions/workflows/integration.yml) [](https://github.com/grafana/mcp-grafana/actions/workflows/e2e.yml) [](https://pkg.go.dev/github.com/grafana/mcp-grafana) [](https://archestra.ai/mcp-catalog/grafana__mcp-grafana) 一个用于 Grafana 的 [Model Context Protocol][mcp] (MCP) server。 这提供了访问您的 Grafana 实例及其周围生态系统的能力。 ## 快速开始 需要 [uv](https://docs.astral.sh/uv/getting-started/installation/)。将以下内容添加到您的 MCP client 配置中（例如 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、binary 和 Helm 在内的更多安装选项，请参阅[用法](#usage)。 ## 要求 - **Grafana 版本 9.0 或更高版本**是完整功能所需。某些功能，特别是 datasource 相关操作，由于缺少 API endpoints，可能在早期版本中无法正常工作。 ## 功能 _以下功能目前在 MCP server 中可用。此列表仅供参考，并不代表路线图或对未来功能的承诺。_ ### 仪表盘 - **Search for dashboards:** 按标题或其他元数据查找 dashboards - **Get dashboard by UID:** 使用其唯一标识符检索完整的 dashboard 详情。_警告：大型 dashboards 可能会占用大量 context window 空间。_ - **Get dashboard summary:** 获取 dashboard 的紧凑概览，包括标题、panel 数量、panel 类型、变量和元数据，而无需完整的 JSON 以最小化 context window 使用 - **Get dashboard property:** 使用 JSONPath 表达式提取 dashboard 的特定部分（例如 `$.title`、`$.panels[*].title`），以仅获取所需数据并减少 context window 消耗 - **Update or create a dashboard:** 修改现有 dashboards 或创建新的 dashboards。_警告：需要完整的 dashboard JSON，这可能会消耗大量 context window 空间。_ - **Patch dashboard:** 对 dashboard 应用特定更改而无需完整 JSON，显著减少针对目标修改的 context window 使用 - **Get panel queries and datasource info:** 从 dashboard 中的每个 panel 获取标题、查询字符串和 datasource 信息（包括 UID 和类型，如果可用） ### 运行面板查询 - **Run panel query:** 使用自定义时间范围和变量覆盖执行 dashboard panel 的查询。 #### Context Window 管理 dashboard 工具现在包含几种有效管理 context window 使用的策略 ([issue #101](https://github.com/grafana/mcp-grafana/issues/101))： - **使用 `get_dashboard_summary`** 进行 dashboard 概览和规划修改 - **使用 `get_dashboard_property`** 配合 JSONPath，当您只需要特定 dashboard 部分时 - **避免 `get_dashboard_by_uid`**，除非您特别需要完整的 dashboard JSON ### 数据源 - **List and fetch datasource information:** 查看所有配置的 datasources 并检索每个的详细信息。 - _支持的 datasource 类型：Prometheus, Loki, ClickHouse, CloudWatch, Elasticsearch。_ ### 查询示例 - **Get query examples:** 检索不同 datasource 类型的示例查询以学习查询语法。 ### Prometheus 查询 - **Query Prometheus:** 针对 Prometheus datasources 执行 PromQL 查询（支持 instant 和 range metric 查询）。 - **Query Prometheus metadata:** 从 Prometheus datasources 检索 metric metadata、metric 名称、label 名称和 label 值。 - **Query histogram percentiles:** 使用 histogram_quantile 计算直方图百分位值（p50, p90, p95, p99）。 ### Loki 查询 - **Query Loki logs and metrics:** 针对 Loki datasources 使用 LogQL 运行日志查询和 metric 查询。 - **Query Loki metadata:** 从 Loki datasources 检索 label 名称、label 值和 stream 统计信息。 - **Query Loki patterns:** 检索 Loki 检测到的日志模式，以识别常见的日志结构和异常。 ### ClickHouse 查询 - **List ClickHouse tables:** 列出 ClickHouse 数据库中的所有表，包括行数和大小。 - **Describe table schema:** 获取 ClickHouse 表的列名、类型和元数据。 - **Query ClickHouse:** 执行支持 Grafana 宏和变量替换的 SQL 查询。 ### CloudWatch 查询 - **List CloudWatch namespaces:** 发现可用的 AWS CloudWatch namespaces。 - **List CloudWatch metrics:** 列出特定 namespace 中可用的 metrics。 - **List CloudWatch dimensions:** 获取用于过滤 metric 查询的 dimensions。 - **Query CloudWatch:** 执行支持时间范围的 CloudWatch metric 查询。 ### 日志搜索 - **Search logs:** 跨 ClickHouse（OTel 格式）和 Loki datasources 的高级日志搜索。 ### Elasticsearch 查询 - **Query Elasticsearch:** 针对 Elasticsearch datasources 使用 Lucene 查询语法或 Elasticsearch Query DSL 执行搜索查询。支持按时间范围过滤并检索日志、metrics 或任何索引数据。返回文档及其 index、ID、source 字段和可选的相关性分数。 ### 事件 - **Search, create, and update incidents:** 在 Grafana Incident 中管理 incidents，包括搜索、创建和向 incidents 添加活动。 ### Sift Investigations - **List Sift investigations:** 检索 Sift investigations 列表，支持 limit 参数。 - **Get Sift investigation:** 通过 UUID 检索特定 Sift investigation 的详情。 - **Get Sift analyses:** 从 Sift investigation 中检索特定分析。 - **Find error patterns in logs:** 使用 Sift 检测 Loki 日志中的错误模式。 - **Find slow requests:** 使用 Sift (Tempo) 检测慢请求。 ### 告警 - **List and fetch alert rule information:** 查看 Grafana 中的告警规则及其状态（firing/normal/error 等）。支持 Grafana 管理的规则和来自 Prometheus 或 Loki datasources 的 datasource 管理规则。 - **Create and update alert rules:** 创建新的告警规则或修改现有的。 - **Delete alert rules:** 通过 UID 删除告警规则。 - **List contact points:** 查看 Grafana 中配置的通知 contact points。支持 Grafana 管理的 contact points 和来自外部 Alertmanager datasources（Prometheus Alertmanager, Mimir, Cortex）的 receivers。 ### Grafana OnCall - **List and manage schedules:** 在 Grafana OnCall 中查看和管理 on-call 日程。 - **Get shift details:** 检索特定 on-call shifts 的详细信息。 - **Get current on-call users:** 查看当前哪些用户处于 on-call 状态。 - **List teams and users:** 查看所有 OnCall teams 和 users。 - **List alert groups:** 从 Grafana OnCall 查看和过滤 alert groups，可按各种条件过滤，包括状态、integration、labels 和时间范围。 - **Get alert group details:** 通过 ID 检索特定 alert group 的详细信息。 ### 管理 - **List teams:** 查看 Grafana 中所有配置的 teams。 - **List Users:** 查看 Grafana 中 organization 的所有 users。 - **List all roles:** 列出所有 Grafana roles，带有可选的可委托 roles 过滤。 - **Get role details:** 通过 UID 获取特定 Grafana role 的详情。 - **List assignments for a role:** 列出分配给 role 的所有 users、teams 和 service accounts。 - **List roles for users:** 列出分配给一个或多个 users 的所有 roles。 - **List roles for teams:** 列出分配给一个或多个 teams 的所有 roles。 - **List permissions for a resource:** 列出为特定资源（dashboard、datasource、folder 等）定义的所有 permissions。 - **Describe a Grafana resource:** 列出资源类型的可用 permissions 和分配能力。 ### 导航 - **Generate deeplinks:** 为 Grafana 资源创建准确的 deeplink URL，而不是依赖 LLM URL 猜测。 - **Dashboard links:** 使用 UID 生成指向 dashboards 的直接链接（例如 `http://localhost:3000/d/dashboard-uid`） - **Panel links:** 使用 viewPanel 参数创建指向 dashboards 内特定 panels 的链接（例如 `http://localhost:3000/d/dashboard-uid?viewPanel=5`） - **Explore links:** 生成带有预配置 datasources 的 Grafana Explore 链接（例如 `http://localhost:3000/explore?left={"datasource":"prometheus-uid"}`） - **Time range support:** 向链接添加时间范围参数（`from=now-1h&to=now`） - **Custom parameters:** 包含额外的查询参数，如 dashboard 变量或刷新间隔 ### 注释 - **Get Annotations:** 使用过滤器查询 annotations。支持时间范围、dashboard UID、tags 和匹配模式。 - **Create Annotation:** 在 dashboard 或 panel 上创建新的 annotation。 - **Create Graphite Annotation:** 使用 Graphite 格式（`what`、`when`、`tags`、`data`）创建 annotations。 - **Update Annotation:** 替换现有 annotation 的所有字段（完整更新）。 - **Patch Annotation:** 仅更新 annotation 的特定字段（部分更新）。 - **Get Annotation Tags:** 列出可用的 annotation tags，可选过滤。 ### 渲染 - **Get panel or dashboard image:** 将 Grafana dashboard panel 或完整 dashboard 渲染为 PNG 图像。返回 base64 编码的数据，用于报告、alerts 或演示。支持自定义尺寸、时间范围、主题、缩放和 dashboard 变量。 - _注意：需要安装并配置 [Grafana Image Renderer](https://grafana.com/docs/grafana/latest/setup-grafana/image-rendering/) 服务。_ 工具列表是可配置的，因此您可以选择哪些工具可用于 MCP client。 如果您不使用某些功能，或者不想占用太多 context window，这很有用。 要禁用某一类工具，请在启动 server 时使用 `--disable-` 标志。例如，要禁用 OnCall 工具，使用 `--disable-oncall`，或要禁用 navigation deeplink 生成，使用 `--disable-navigation`。 #### RBAC 权限 每个工具都需要特定的 RBAC permissions 才能正常运行。为 MCP server 创建 service account 时，请确保根据您计划使用的工具为其授予必要的 permissions。列出的 permissions 是所需的最低操作 - 您可能还需要适当的 scopes（例如 `datasources:*`、`dashboards:*`、`folders:*`），具体取决于您的用例。 提示：如果您不熟悉 Grafana RBAC，或者您想要更快速、简单的设置而不是配置许多细粒度的 scopes，您可以将内置角色（如 `Editor`）分配给 service account。`Editor` 角色授予广泛的读/写访问权限，这将允许大多数 MCP server 操作；它不如手动应用的 scopes 细粒度（因此限制较少），因此仅在便利性比严格的最小权限访问更重要时使用它。 **注意：** Grafana Incident 和 Sift 工具使用基本的 Grafana roles 而不是细粒度的 RBAC permissions： - **Viewer role:** 只读操作所需（list incidents、get investigations） - **Editor role:** 写入操作所需（create incidents、modify investigations） 有关 Grafana RBAC 的更多信息，请参阅[官方文档](https://grafana.com/docs/grafana/latest/administration/roles-and-permissions/access-control/)。 #### RBAC Scopes Scopes 定义 permissions 适用的特定资源。每个操作都需要适当的 permission 和 scope 组合。 **常见 Scope 模式：** - **广泛访问：** 使用 `*` 通配符进行组织范围的访问 - `datasources:*` - 访问所有 datasources - `dashboards:*` - 访问所有 dashboards - `folders:*` - 访问所有 folders - `teams:*` - 访问所有 teams - **有限访问：** 使用特定的 UID 或 ID 来限制对单个资源的访问 - `datasources:uid:prometheus-uid` - 仅访问特定的 Prometheus datasource - `dashboards:uid:abc123` - 仅访问 UID 为 `abc123` 的 dashboard - `folders:uid:xyz789` - 仅访问 UID 为 `xyz789` 的 folder - `teams:id:5` - 仅访问 ID 为 `5` 的 team - `global.users:id:123` - 仅访问 ID 为 `123` 的 user **示例：** - **完整 MCP server 访问：** 为所有工具授予广泛权限 datasources:* (datasources:read, datasources:query) dashboards:* (dashboards:read, dashboards:create, dashboards:write) folders:* (用于 dashboard 创建和告警规则) teams:* (teams:read) global.users:* (users:read) - **有限 datasource 访问：** 仅查询特定的 Prometheus 和 Loki 实例 datasources:uid:prometheus-prod (datasources:query) datasources:uid:loki-prod (datasources:query) - **特定 Dashboard 访问：** 仅读取特定 dashboards dashboards:uid:monitoring-dashboard (dashboards:read) dashboards:uid:alerts-dashboard (dashboards:read) ### 工具 | Tool | Category | Description | Required RBAC | Required Scopes | | --------------------------------- | ----------- | ------------------------------------------------------------------- | --------------------------------------- | --------------------------------------------------- | | `list_teams` | Admin | 列出所有 teams | `teams:read` | `teams:*` or `teams:id:1` | | `list_users_by_org` | Admin | 列出 organization 中的所有 users | `users:read` | `global.users:*` or `global.users:id:123` | | `list_all_roles` | Admin | 列出所有 Grafana roles | `roles:read` | `roles:*` | | `get_role_details` | Admin | 获取 Grafana role 的详情 | `roles:read` | `roles:uid:editor` | | `get_role_assignments` | Admin | 列出 role 的分配 | `roles:read` | `roles:uid:editor` | | `list_user_roles` | Admin | 列出 users 的 roles | `roles:read` | `global.users:id:123` | | `list_team_roles` | Admin | 列出 teams 的 roles | `roles:read` | `teams:id:7` | | `get_resource_permissions`| Admin | 列出资源的 permissions | `permissions:read` | `dashboards:uid:abcd1234` | | `get_resource_description`| Admin | 描述 Grafana 资源类型 | `permissions:read` | `dashboards:*` | | `search_dashboards` | Search | 搜索 dashboards | `dashboards:read` | `dashboards:*` or `dashboards:uid:abc123` | | `get_dashboard_by_uid` | Dashboard | 通过 uid 获取 dashboard | `dashboards:read` | `dashboards:uid:abc123` | | `update_dashboard` | Dashboard | 更新或创建新的 dashboard | `dashboards:create`, `dashboards:write` | `dashboards:*`, `folders:*` or `folders:uid:xyz789` | | `get_dashboard_panel_queries` | Dashboard | 从 dashboard 获取 panel 标题、queries、datasource UID 和类型 | `dashboards:read` | `dashboards:uid:abc123` | | `run_panel_query` | RunPanelQuery* | 执行一个或多个 dashboard panel 查询 | `dashboards:read`, `datasources:query` | `dashboards:uid:*`, `datasources:uid:*` | | `get_dashboard_property` | Dashboard | 使用 JSONPath 表达式提取 dashboard 的特定部分 | `dashboards:read` | `dashboards:uid:abc123` | | `get_dashboard_summary` | Dashboard | 获取 dashboard 的紧凑摘要，无完整 JSON | `dashboards:read` | `dashboards:uid:abc123` | | `list_datasources` | Datasources | 列出 datasources | `datasources:read` | `datasources:*` | | `get_datasource` | Datasources | 通过 UID 或名称获取 datasource | `datasources:read` | `datasources:uid:prometheus-uid` | | `get_query_examples` | Examples* | 获取 datasource 类型的示例查询 | `datasources:read` | `datasources:*` | | `query_prometheus` | Prometheus | 针对 Prometheus datasource 执行查询 | `datasources:query` | `datasources:uid:prometheus-uid` | | `list_prometheus_metric_metadata` | Prometheus | 列出 metric metadata | `datasources:query` | `datasources:uid:prometheus-uid` | | `list_prometheus_metric_names` | Prometheus | 列出可用的 metric 名称 | `datasources:query` | `datasources:uid:prometheus-uid` | | `list_prometheus_label_names` | Prometheus | 列出匹配选择器的 label 名称 | `datasources:query` | `datasources:uid:prometheus-uid` | | `list_prometheus_label_values` | Prometheus | 列出特定 label 的值 | `datasources:query` | `datasources:uid:prometheus-uid` | | `query_prometheus_histogram` | Prometheus | 计算直方图百分位值 | `datasources:query` | `datasources:uid:prometheus-uid` | | `list_incidents` | Incident | 列出 Grafana Incident 中的 incidents | Viewer role | N/A | | `create_incident` | Incident | 在 Grafana Incident 中创建 incident | Editor role | N/A | | `add_activity_to_incident` | Incident | 向 Grafana Incident 中的 incident 添加活动项 | Editor role | N/A | | `get_incident` | Incident | 通过 ID 获取单个 incident | Viewer role | N/A | | `query_loki_logs` | Loki | 使用 LogQL 查询和检索日志（日志或 metric 查询） | `datasources:query` | `datasources:uid:loki-uid` | | `list_loki_label_names` | Loki | 列出日志中所有可用的 label 名称 | `datasources:query` | `datasources:uid:loki-uid` | | `list_loki_label_values` | Loki | 列出特定日志 label 的值 | `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` | | `list_clickhouse_tables` | ClickHouse* | 列出 ClickHouse 数据库中的表 | `datasources:query` | `datasources:uid:*` | | `describe_clickhouse_table` | ClickHouse* | 获取带有列类型的表 schema | `datasources:query` | `datasources:uid:*` | | `query_clickhouse` | ClickHouse* | 执行带有宏替换的 SQL 查询 | `datasources:query` | `datasources:uid:*` | | `list_cloudwatch_namespaces` | CloudWatch* | 列出可用的 AWS CloudWatch namespaces | `datasources:query` | `datasources:uid:*` | | `list_cloudwatch_metrics` | CloudWatch* | 列出 namespace 中的 metrics | `datasources:query` | `datasources:uid:*` | | `list_cloudwatch_dimensions` | CloudWatch* | 列出 metric 的 dimensions | `datasources:query` | `datasources:uid:*` | | `query_cloudwatch` | CloudWatch* | 执行 CloudWatch metric 查询 | `datasources:query` | `datasources:uid:*` | | `search_logs` | SearchLogs* | 跨 ClickHouse 和 Loki 搜索日志 | `datasources:query` | `datasources:uid:*` | | `query_elasticsearch` | Elasticsearch* | 使用 Lucene 语法或 Query DSL 查询 Elasticsearch | `datasources:query` | `datasources:uid:elasticsearch-uid` | | `list_alert_rules` | Alerting | 列出告警规则 | `alert.rules:read` | `folders:*` or `folders:uid:alerts-folder` | | `get_alert_rule_by_uid` | Alerting | 通过 UID 获取告警规则 | `alert.rules:read` | `folders:uid:alerts-folder` | | `create_alert_rule` | Alerting | 创建新的告警规则 | `alert.rules:write` | `folders:*` or `folders:uid:alerts-folder` | | `update_alert_rule` | Alerting | 更新现有的告警规则 | `alert.rules:write` | `folders:uid:alerts-folder` | | `delete_alert_rule` | Alerting | 通过 UID 删除告警规则 | `alert.rules:write` | `folders:uid:alerts-folder` | | `list_contact_points` | Alerting | 列出通知 contact points（Grafana 管理和 Alertmanager） | `alert.notifications:read` | Global scope | | `list_oncall_schedules` | OnCall | 列出 Grafana OnCall 的日程 | `grafana-oncall-app.schedules:read` | Plugin-specific scopes | | `get_oncall_shift` | OnCall | 获取特定 OnCall shift 的详情 | `grafana-oncall-app.schedules:read` | Plugin-specific scopes | | `get_current_oncall_users` | OnCall | 获取当前特定日程 on-call 的 users | `grafana-oncall-app.schedules:read` | Plugin-specific scopes | | `list_oncall_teams` | OnCall | 列出 Grafana OnCall 的 teams | `grafana-oncall-app.user-settings:read` | Plugin-specific scopes | | `list_oncall_users` | OnCall | 列出 Grafana OnCall 的 users | `grafana-oncall-app.user-settings:read` | Plugin-specific scopes | | `list_alert_groups` | OnCall | 列出带有过滤选项的 Grafana OnCall alert groups | `grafana-oncall-app.alert-groups:read` | Plugin-specific scopes | | `get_alert_group` | OnCall | 通过 ID 获取特定的 Grafana OnCall alert group | `grafana-oncall-app.alert-groups:read` | Plugin-specific scopes | | `get_sift_investigation` | Sift | 通过 UUID 检索现有的 Sift investigation | Viewer role | N/A | | `get_sift_analysis` | Sift | 从 Sift investigation 检索特定分析 | Viewer role | N/A | | `list_sift_investigations` | Sift | 检索带有可选 limit 的 Sift investigations 列表 | Viewer role | N/A | | `find_error_pattern_logs` | Sift | 查找 Loki 日志中的错误模式 | Editor role | N/A | | `find_slow_requests` | Sift | 从相关的 tempo datasources 查找慢请求 | Editor role | N/A | | `list_pyroscope_label_names` | Pyroscope | 列出匹配选择器的 label 名称 | `datasources:query` | `datasources:uid:pyroscope-uid` | | `list_pyroscope_label_values` | Pyroscope | 列出特定 label 名称的选择器匹配的 label 值 | `datasources:query` | `datasources:uid:pyroscope-uid` | | `list_pyroscope_profile_types` | Pyroscope | 列出可用的 profile 类型 | `datasources:query` | `datasources:uid:pyroscope-uid` | | `fetch_pyroscope_profile` | Pyroscope | 以 DOT 格式获取 profile 用于分析 | `datasources:query` | `datasources:uid:pyroscope-uid` | | `get_assertions` | Asserts | 获取给定实体的断言摘要 | Plugin-specific permissions | Plugin-specific scopes | | `generate_deeplink` | Navigation | 为 Grafana 资源生成准确的 deeplink URL | None (read-only URL generation) | N/A | | `get_annotations` | Annotations | 使用过滤器获取 annotations | `annotations:read` | `annotations:*` or `annotations:id:123` | | `create_annotation` | Annotations | 创建新的 annotation（标准或 Graphite 格式） | `annotations:write` | `annotations:*` | | `update_annotation` | Annotations | 更新 annotation 的特定字段（部分更新） | `annotations:write` | `annotations:*` | | `get_annotation_tags` | Annotations | 列出 annotation tags，可选过滤 | `annotations:read` | `annotations:*` | | `get_panel_image` | Rendering | 将 dashboard panel 或完整 dashboard 渲染为 PNG 图像 | `dashboards:read` | `dashboards:uid:abc123` | _* 默认禁用。将 category 添加到 `--enabled-tools` 以启用。_ ## CLI Flags 参考 `mcp-grafana` binary 支持各种用于配置的命令行 flags： **Transport Options:** - `-t, --transport`: Transport 类型（`stdio`、`sse` 或 `streamable-http`）- 默认：`stdio` - `--address`: SSE/streamable-http server 的主机和端口 - 默认：`localhost:8000` - `--base-path`: SSE/streamable-http server 的 base path - `--endpoint-path`: streamable-http server 的 endpoint path - 默认：`/` **Debug and Logging:** - `--debug`: 启用 debug 模式以进行详细的 HTTP 请求/响应日志记录 - `--log-level`: 日志级别（`debug`、`info`、`warn`、`error`）- 默认：`info` **Observability:** - `--metrics`: 在 `/metrics` 启用 Prometheus metrics endpoint - `--metrics-address`: metrics server 的单独地址（例如 `:9090`）。如果为空，metrics 将在主 server 上提供服务 **Tool Configuration:** - `--enabled-tools`: 启用 categories 的逗号分隔列表 - 默认：除 `admin` 外的所有 categories，要启用 admin 工具，请将 `admin` 添加到列表中（例如 `"search,datasource,...,admin"`） - `--disable-search`: 禁用 search 工具 - `--disable-datasource`: 禁用 datasource 工具 - `--disable-incident`: 禁用 incident 工具 - `--disable-prom`: 禁用 prometheus 工具 - `--disable-write`: 禁用 write 工具（创建/更新操作） - `--disable-loki`: 禁用 loki 工具 - `--disable-elasticsearch`: 禁用 elasticsearch 工具 - `--disable-alerting`: 禁用 alerting 工具 - `--disable-dashboard`: 禁用 dashboard 工具 - `--disable-oncall`: 禁用 oncall 工具 - `--disable-asserts`: 禁用 asserts 工具 - `--disable-sift`: 禁用 sift 工具 - `--disable-admin`: 禁用 admin 工具 - `--disable-pyroscope`: 禁用 pyroscope 工具 - `--disable-navigation`: 禁用 navigation 工具 - `--disable-rendering`: 禁用 rendering 工具（panel/dashboard 图像导出） - `--disable-cloudwatch`: 禁用 CloudWatch 工具 - `--disable-examples`: 禁用 query examples 工具 - `--disable-clickhouse`: 禁用 ClickHouse 工具 - `--disable-searchlogs`: 禁用 search_logs 工具 - `--disable-runpanelquery`: 禁用 run panel query 工具 ### 只读模式 `--disable-write` flag 提供了一种以只读模式运行 MCP server 的方法，防止对您的 Grafana 实例进行任何写入操作。这对于您希望提供安全的只读访问权限的场景很有用，例如： - 使用权限有限的 service accounts - 向 AI assistants 提供 observability 数据，但不具备修改能力 - 在应限制写入访问的生产环境中运行 - 在测试和开发场景中，您希望防止意外修改 当启用 `--disable-write` 时，以下写入操作将被禁用： **Dashboard Tools:** - `update_dashboard` **Folder Tools:** - `create_folder` **Incident Tools:** - `create_incident` - `add_activity_to_incident` **Alerting Tools:** - `create_alert_rule` - `update_alert_rule` - `delete_alert_rule` **Annotation Tools:** - `create_annotation` - `update_annotation` **Sift Tools:** - `find_error_pattern_logs`（创建 investigations） - `find_slow_requests`（创建 investigations） 所有读取操作仍然可用，允许您查询 dashboards、运行 PromQL/LogQL 查询、列出资源和检索数据。 **Client TLS Configuration（用于 Grafana 连接）:** - `--tls-cert-file`: 用于客户端身份验证的 TLS 证书文件路径 - `--tls-key-file`: 用于客户端身份验证的 TLS 私钥文件路径 - `--tls-ca-file`: 用于服务器验证的 TLS CA 证书文件路径 - `--tls-skip-verify`: 跳过 TLS 证书验证（不安全） **Server TLS Configuration（仅限 streamable-http transport）:** - `--server.tls-cert-file`: 用于服务器 HTTPS 的 TLS 证书文件路径 - `--server.tls-key-file`: 用于服务器 HTTPS 的 TLS 私钥文件路径 ## 使用方法 此 MCP server 适用于本地 Grafana 实例和 Grafana Cloud。对于 Grafana Cloud，请使用您的实例 URL（例如 `https://myinstance.grafana.net`）而不是 `http://localhost:3000`。 1. 如果使用 service account token 身份验证，请在 Grafana 中创建一个具有足够权限的 service account 以使用您想用的工具， 生成 service account token 并将其复制到剪贴板以便在配置文件中使用。 有关创建 service account tokens 的详细信息，请遵循 [Grafana service account 文档][service-account]。 提示：如果您不习惯配置细粒度的 RBAC scopes，一个更简单（但限制较少）的选择是将内置的 `Editor` 角色分配给 service account。这授予了涵盖大多数 MCP server 操作的广泛读/写访问权限 —— 当便利性胜过严格的最小权限要求时使用它。 ### 多组织支持 您可以使用以下任一方式指定要与之交互的 organization： - **Environment variable:** 将 `GRAFANA_ORG_ID` 设置为数字 organization ID - **HTTP header:** 在使用 SSE 或 streamable HTTP transports 时设置 `X-Grafana-Org-Id`（header 优先于环境变量 - 这意味着您也可以设置默认 org）。 当提供 organization ID 时，MCP server 将在所有对 Grafana 的请求中设置 `X-Grafana-Org-Id` header，确保操作在指定的 organization context 中执行。 **带有 organization ID 的示例：** ``` { "mcpServers": { "grafana": { "command": "mcp-grafana", "args": [], "env": { "GRAFANA_URL": "http://localhost:3000", "GRAFANA_USERNAME": "", "GRAFANA_PASSWORD": "", "GRAFANA_ORG_ID": "2" } } } } ``` ### 自定义 HTTP Headers 您可以使用 `GRAFANA_EXTRA_HEADERS` 环境变量向所有 Grafana API 请求添加任意 HTTP headers。该值应该是一个将 header 名称映射到值的 JSON 对象。 **带有 custom headers 的示例：** ``` { "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\"}" } } } } ``` 2. 您有多种安装 `mcp-grafana` 的选择： - **uvx (recommended)**: 如果您安装了 [uv](https://docs.astral.sh/uv/getting-started/installation/)，则不需要额外设置 — `uvx` 将自动下载并运行 server： uvx mcp-grafana - **Docker image**: 使用 Docker Hub 上的预构建 Docker image。 **重要**：Docker image 的 entrypoint 配置为默认在 SSE 模式下运行 MCP server，但大多数用户会希望使用 STDIO 模式以便与 Claude Desktop 等 AI assistants 直接集成： 1. **STDIO Mode**: 对于 stdio 模式，您必须使用 `-t stdio` 显式覆盖默认值，并包含 `-i` flag 以保持 stdin 打开： docker pull grafana/mcp-grafana # 对于本地 Grafana： docker run --rm -i -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN= grafana/mcp-grafana -t stdio # 对于 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 Mode**: 在此模式下，server 作为 HTTP server 运行，clients 连接到该 server。您必须使用 `-p` flag 暴露端口 8000： 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. **Streamable HTTP Mode**: 在此模式下，server 作为独立进程运行，可以处理多个 client 连接。您必须使用 `-p` flag 暴露端口 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= grafana/mcp-grafana -t streamable-http 对于带有 server 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= \ grafana/mcp-grafana \ -t streamable-http \ -addr :8443 \ --server.tls-cert-file /certs/server.crt \ --server.tls-key-file /certs/server.key - **Download binary**: 从 [releases page](https://github.com/grafana/mcp-grafana/releases) 下载最新版本的 `mcp-grafana` 并将其放在您的 `$PATH` 中。 - **Build from source**: 如果您安装了 Go toolchain，您也可以从源代码构建并安装它，使用 `GOBIN` 环境变量 指定 binary 应安装到的目录。这也应该在您的 `PATH` 中。 GOBIN="$HOME/go/bin" go install github.com/grafana/mcp-grafana/cmd/mcp-grafana@latest - **Deploy to Kubernetes using Helm**: 使用 [Grafana helm-charts repository 中的 Helm chart](https://github.com/grafana/helm-charts/tree/main/charts/grafana-mcp) helm repo add grafana https://grafana.github.io/helm-charts helm install --set grafana.apiKey= --set grafana.url= my-release grafana/grafana-mcp 3. 将 server 配置添加到您的 client 配置文件。例如，对于 Claude Desktop： **If using uvx:** { "mcpServers": { "grafana": { "command": "uvx", "args": ["mcp-grafana"], "env": { "GRAFANA_URL": "http://localhost:3000", "GRAFANA_SERVICE_ACCOUNT_TOKEN": "" } } } } **If using the binary:** { "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" } } } } **If using 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" } } } } ``` **Using VSCode with remote MCP server** 如果您使用 VSCode 并在 SSE 模式下运行 MCP server（这是在不覆盖 transport 的情况下使用 Docker image 时的默认模式），请确保您的 `.vscode/settings.json` 包含以下内容： ``` "mcp": { "servers": { "grafana": { "type": "sse", "url": "http://localhost:8000/sse" } } } ``` 对于带有 server TLS 证书的 HTTPS streamable HTTP 模式： ``` "mcp": { "servers": { "grafana": { "type": "sse", "url": "https://localhost:8443/sse" } } } ``` ### Debug Mode 您可以通过向命令添加 `-debug` flag 来启用 Grafana transport 的 debug 模式。这将提供 MCP server 和 Grafana API 之间 HTTP 请求和响应的详细日志记录，这对于故障排除很有帮助。 要将 debug 模式与 Claude Desktop 配置一起使用，请按如下方式更新您的配置： **If using the binary:** ``` { "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": "" } } } } ``` **If using 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": "" } } } } ``` ### TLS 配置 如果您的 Grafana 实例在 mTLS 之后或需要自定义 TLS 证书，您可以配置 MCP server 使用自定义证书。Server 支持以下 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 server 使用的所有 HTTP clients，包括： - The main Grafana OpenAPI client - Prometheus datasource clients - Loki datasource clients - Incident management clients - Sift investigation clients - Alerting clients - Asserts clients **Direct CLI Usage Examples:** 用于使用自签名证书进行测试： ``` ./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 ``` **Programmatic Usage:** 如果您以编程方式使用此库，您还可以创建启用 TLS 的 context 函数： ``` // 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) ``` ### 服务器 TLS 配置（仅限 Streamable HTTP Transport） 当使用 streamable HTTP transport（`-t streamable-http`）时，您可以配置 MCP server 提供 HTTPS 而不是 HTTP。当您需要保护 MCP client 和 server 本身之间的连接时，这很有用。 Server 为 streamable HTTP transport 支持以下 TLS 配置选项： - `--server.tls-cert-file`: 用于服务器 HTTPS 的 TLS 证书文件路径（TLS 必需） - `--server.tls-key-file`: 用于服务器 HTTPS 的 TLS 私钥文件路径（TLS 必需） **注意**：这些 flags 与上面记录的 client TLS flags 完全分开。Client TLS flags 配置 MCP server 如何连接到 Grafana，而这些 server TLS flags 配置 clients 在使用 streamable HTTP transport 时如何连接到 MCP server。 **带有 HTTPS streamable HTTP server 的示例：** ``` ./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 server。然后 Clients 将连接到 `https://localhost:8443/` 而不是 `http://localhost:8000/`。 **带有 server 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`）或 streamable HTTP（`-t streamable-http`）transports 时，MCP server 在 `/healthz` 暴露一个 health check endpoint。此 endpoint 可被 load balancers、monitoring systems 或 orchestration platforms 用于验证 server 是否正在运行并接受连接。 **Endpoint:**GET /healthz` **Response:** - Status Code: `200 OK` - Body: `ok` **Example usage:** ``` # 在默认端口上使用 Streamable HTTP 或 SSE 传输 curl http://localhost:8000/healthz # 使用自定义地址 curl http://localhost:9090/healthz ``` **注意：** Health check endpoint 仅在使用 SSE 或 streamable HTTP transports 时可用。在使用 stdio transport（`-t stdio`）时不可用，因为 stdio 不暴露 HTTP server。 ### 可观测性 MCP server 支持 Prometheus metrics 和 OpenTelemetry distributed tracing，遵循 [OTel MCP semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/mcp/)。 #### 指标 当使用 SSE 或 streamable HTTP transports 时，使用 `--metrics` flag 启用 Prometheus metrics： ``` # 在主服务器的 /metrics 端点提供指标 ./mcp-grafana -t streamable-http --metrics # 在单独的地址提供指标 ./mcp-grafana -t streamable-http --metrics --metrics-address :9090 ``` **Available Metrics:** | Metric | Type | Description | |--------|------|-------------| | `mcp_server_operation_duration_seconds` | Histogram | MCP 操作持续时间（labels: `mcp_method_name`, `gen_ai_tool_name`, `error_type`, `network_transport`, `mcp_protocol_version`） | | `mcp_server_session_duration_seconds` | Histogram | MCP client sessions 持续时间（labels: `network_transport`, `mcp_protocol_version`） | | `http_server_request_duration_seconds` | Histogram | HTTP server 请求持续时间（来自 otelhttp） | **注意：** Metrics 仅在使用 SSE 或 streamable HTTP transports 时可用。在 stdio transport 下不可用。 #### Tracing Distributed tracing 通过标准 `OTEL_*` 环境变量配置，并且独立于 `--metrics` flag 工作。当设置 `OTEL_EXPORTER_OTLP_ENDPOINT` 时，server 通过 OTLP/gRPC 导出 traces： ``` # 发送 Traces 到本地 Tempo 实例 OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 \ OTEL_EXPORTER_OTLP_INSECURE=true \ ./mcp-grafana -t streamable-http # 发送 Traces 到 Grafana Cloud 并进行身份验证 OTEL_EXPORTER_OTLP_ENDPOINT=https://tempo-us-central1.grafana.net:443 \ OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic ..." \ ./mcp-grafana -t streamable-http ``` Tool call spans 遵循 semconv 命名（`tools/call `）并包含 `gen_ai.tool.name`、`mcp.method.name` 和 `mcp.session.id` 等属性。Server 还支持来自 tool call requests 的 `_meta` 字段的 W3C trace context propagation。 **带有 metrics 和 tracing 的 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 版本兼容性 如果您在使用 datasource-related 工具时遇到以下错误： ``` get datasource by uid : [GET /datasources/uid/{uid}][400] getDataSourceByUidBadRequest {"message":"id is invalid"} ``` 这通常表明您使用的是 Grafana 9.0 之前的版本。`/datasources/uid/{uid}` API endpoint 是在 Grafana 9.0 中引入的，datasource 操作在早期版本中将失败。 **Solution:** 将您的 Grafana 实例升级到版本 9.0 或更高版本以解决此问题。 ## 开发 欢迎贡献！如果您有任何建议或改进，请 open an issue 或提交 pull request。 该项目使用 Go 编写。请按照您平台的说明安装 Go。 要在本地以 STDIO 模式（这是本地开发的默认设置）运行 server，请使用： ``` make run ``` 要在本地以 SSE 模式运行 server，请使用： ``` go run ./cmd/mcp-grafana --transport sse ``` 您也可以在自定义构建的 Docker image 中使用 SSE transport 运行 server。与发布的 Docker image 一样，此自定义 image 的 entrypoint 默认为 SSE 模式。要构建 image，请使用： ``` make build-image ``` 要在 SSE 模式（默认）下运行 image，请使用： ``` docker run -it --rm -p 8000:8000 mcp-grafana:latest ``` 如果您需要改为在 STDIO 模式下运行它，请覆盖 transport 设置： ``` docker run -it --rm mcp-grafana:latest -t stdio ``` ### 测试 有三种类型的测试可用： 1. Unit Tests（不需要外部依赖）： ``` make test-unit ``` 您也可以使用以下命令运行 unit tests： ``` make test ``` 2. Integration Tests（需要 docker containers 启动并运行）： ``` make test-integration ``` 3. Cloud Tests（需要 cloud Grafana 实例和凭据）： ``` make test-cloud ``` 更全面的 integration tests 将需要在本地端口 3000 上运行 Grafana 实例；您可以使用 Docker Compose 启动一个： ``` docker-compose up -d ``` Integration tests 可以使用以下命令运行： ``` make test-all ``` 如果您要添加更多工具，请为它们添加 integration tests。现有测试应该是一个很好的起点。 ### Linting 要 lint 代码，请运行： ``` make lint ``` 这包括一个自定义 linter，用于检查 `jsonschema` struct tags 中未转义的逗号。`description` 字段中的逗号必须用 `\\,` 转义，以防止静默截断。您可以仅使用以下命令运行此 linter： ``` make lint-jsonschema ``` 有关更多详细信息，请参阅 [JSONSchema Linter 文档](internal/linter/jsonschema/README.md)。 ## 许可证 该项目根据 [Apache License, Version 2.0](LICENSE) 授权。

标签：API集成, API集成, Claude, Cursor, CVE检测, DevOps工具, DNS解析, Docker, EVTX分析, EVTX分析, EVTX分析, Go语言, Grafana, Helm, LLM工具, Loki, MCP服务器, Model Context Protocol, 仪表盘管理, 可观测性, 可观测性, 安全防御评估, 开源项目, 日志审计, 时间序列数据库, 用户代理, 监控集成, 程序破解, 自动化运维, 自定义请求头, 请求拦截