适合谁
- 已有 Grafana 实例（自建或 Grafana Cloud）并希望通过 AI 助手完成可观测性排查的团队
- 需要在 CI/事件响应流程中自动查询告警、日志和指标的 DevOps/SRE 工程师
- 希望以只读模式安全地向 AI 提供监控数据访问权限的场景
G
72FMRS · B
mcp-grafana 由 Grafana Labs 官方维护，是功能覆盖面很广的 Grafana MCP 服务器，涵盖仪表盘、告警、多类数据源查询、事件管理、OnCall、注解、快照和渲染等能力，并提供细粒度的工具类别开关与只读模式。核心风险集中在凭据管理和写权限的合理限制上：建议按最小权限配置服务账号 RBAC 范围，非必要不启用写工具，并根据实际使用的数据源和功能有选择地启用工具类别以控制上下文占用和攻击面。
mcp-grafana 是 Grafana Labs 官方维护的 Model Context Protocol 服务器，为 AI 助手提供对 Grafana 实例及其生态系统的访问能力，涵盖仪表盘搜索与编辑、Prometheus/Loki/InfluxDB/ClickHouse/CloudWatch/Elasticsearch 等多种数据源查询、告警规则与通知路由管理、Grafana Incident 事件管理、Sift 根因调查、OnCall 排班、注解、快照、面板渲染以及配置仓库校验等功能。工具按类别分组，可通过命令行标志启用或禁用，并支持通过 --disable-write 运行为只读模式。
工具能力
list_teams
列出所有团队
list_users_by_org
列出组织内的所有用户
list_all_roles
列出所有 Grafana 角色
get_role_details
获取某个 Grafana 角色的详细信息
get_role_assignments
列出某角色的所有分配对象
list_user_roles
列出用户被分配的角色
list_team_roles
列出团队被分配的角色
get_resource_permissions
列出某资源（仪表盘、数据源、文件夹等）的所有权限
get_resource_description
描述某类资源可用的权限和分配能力
search_dashboards
按标题或元数据搜索仪表盘
get_dashboard_by_uid
根据 UID 获取仪表盘完整详情
update_dashboard
更新已有仪表盘或创建新仪表盘
get_dashboard_panel_queries
获取仪表盘中每个面板的标题、查询语句和数据源信息
run_panel_query
执行仪表盘面板的查询，支持自定义时间范围和变量覆盖（默认禁用）
get_dashboard_property
使用 JSONPath 表达式提取仪表盘的特定部分
get_dashboard_summary
获取仪表盘的精简摘要（无需完整 JSON）
list_datasources
列出已配置的数据源
get_datasource
根据 UID 或名称获取数据源详情
get_query_examples
获取某类数据源的示例查询（默认禁用）
query_prometheus
对 Prometheus 数据源执行 PromQL 查询（瞬时或范围查询）
list_prometheus_metric_metadata
列出指标元数据
list_prometheus_metric_names
列出可用的指标名称
list_prometheus_label_names
列出匹配选择器的标签名
list_prometheus_label_values
列出某标签的取值
query_prometheus_histogram
计算直方图分位值（如 p50/p90/p95/p99）
list_incidents
在 Grafana Incident 中列出事件
create_incident
在 Grafana Incident 中创建事件
add_activity_to_incident
为事件添加活动记录
get_incident
根据 ID 获取单个事件
query_loki_logs
使用 LogQL 查询 Loki 日志或指标
list_loki_label_names
列出日志中可用的所有标签名
list_loki_label_values
列出某日志标签的取值
query_loki_stats
获取日志流的统计信息
query_loki_patterns
查询 Loki 检测到的日志模式，识别常见结构
analyze_loki_labels
审计 Loki 标签策略（实时或静态）并可诊断查询性能
suggest_loki_alloy_label_config
生成强制执行已批准标签的 Alloy loki.process 配置片段
query_influxdb
使用 InfluxQL(v1) 或 Flux(v2) 查询 InfluxDB（默认禁用）
list_clickhouse_tables
列出 ClickHouse 数据库中的表（默认禁用）
describe_clickhouse_table
获取 ClickHouse 表的列结构（默认禁用）
query_clickhouse
执行支持宏替换的 ClickHouse SQL 查询（默认禁用）
list_cloudwatch_namespaces
列出可用的 AWS CloudWatch 命名空间（默认禁用）
list_cloudwatch_metrics
列出某命名空间下的指标（默认禁用）
list_cloudwatch_dimensions
列出用于过滤指标查询的维度（默认禁用）
query_cloudwatch
执行支持时间范围的 CloudWatch 指标查询（默认禁用）
list_athena_catalogs
列出可用的 Athena 数据目录（默认禁用）
list_athena_databases
列出 Athena 目录中的数据库（默认禁用）
list_athena_tables
列出 Athena 数据库中的表（默认禁用）
describe_athena_table
获取 Athena 表的列名（默认禁用）
query_athena
执行支持宏替换的 Athena SQL 查询（默认禁用）
query_elasticsearch
使用 Lucene 语法或 Query DSL 查询 Elasticsearch/OpenSearch（默认禁用）
query_quickwit
使用 Lucene 语法或 Query DSL 查询 Quickwit（默认禁用）
list_snowflake_tables
通过 INFORMATION_SCHEMA 列出 Snowflake 数据库/schema 中的表（默认禁用）
describe_snowflake_table
获取 Snowflake 表结构（列类型、可空性、默认值、注释）（默认禁用）
query_snowflake
执行支持宏/变量替换的 Snowflake SQL 查询（默认禁用）
alerting_manage_rules
管理告警规则（列出、获取、版本、创建、更新、删除）
alerting_manage_routing
管理通知策略、联系点和时间间隔
list_oncall_schedules
列出 Grafana OnCall 中的排班
get_oncall_shift
获取特定 OnCall 班次的详情
get_current_oncall_users
获取某排班当前值班的用户
list_oncall_teams
列出 Grafana OnCall 团队
list_oncall_users
列出 Grafana OnCall 用户
list_alert_groups
按条件筛选列出 Grafana OnCall 告警组
get_alert_group
根据 ID 获取特定告警组详情
get_sift_investigation
根据 UUID 获取现有 Sift 调查
get_sift_analysis
获取 Sift 调查中的特定分析
list_sift_investigations
获取 Sift 调查列表（可限定数量）
find_error_pattern_logs
检测 Loki 日志中的异常错误模式
find_slow_requests
通过相关 Tempo 数据源检测慢请求
list_pyroscope_label_names
列出匹配选择器的标签名
list_pyroscope_label_values
列出某标签名匹配选择器的标签值
list_pyroscope_profile_types
列出可用的性能剖析类型
query_pyroscope
查询 Pyroscope 的性能剖析数据、指标或两者
get_assertions
获取指定实体的断言摘要
agento11y_manage_conversations
在 Grafana Agent Observability 中列出、搜索并获取 LLM 会话
agento11y_manage_generations
获取 LLM 生成详情及评估分数
agento11y_manage_agents
读取智能体目录：列出智能体、获取完整版本详情、版本历史及各版本评分汇总
agento11y_manage_evaluators
管理评估器、评估器模板和判别模型目录
agento11y_manage_eval_rules
管理评估规则和守护规则（hook rules）
agento11y_manage_eval_collections
管理已保存的会话及其所属集合
ask_assistant
向 Grafana Assistant 发送提示并返回完整文本回复（可通过 contextId 多轮对话）
generate_deeplink
为 Grafana 资源生成准确的深层链接 URL
get_annotations
按过滤条件获取注解
create_annotation
创建新注解（标准格式或 Graphite 格式）
update_annotation
部分更新注解的指定字段
get_annotation_tags
列出可用的注解标签
list_snapshots
按查询条件和数量限制列出仪表盘快照
get_snapshot
根据快照 key 获取快照元数据和仪表盘内容
create_snapshot
根据完整仪表盘内容创建快照
delete_snapshot
根据快照 key 删除快照
get_panel_image
将仪表盘或面板（或配置预览分支）渲染为 PNG 图片
list_provisioning_repositories
列出配置仓库（如 git-sync 源）及其源地址、分支、同步状态和健康状况
validate_provisioning_file
对配置仓库中的文件进行试运行校验，报告准入验证错误
安装接入
- 安装 uv（提供 uvx 命令）。2. 在 Grafana 中创建服务账号并生成令牌（或使用最简单的内置 Editor 角色，或按需配置最小权限的 RBAC 范围）。3. 在 MCP 客户端配置（如 Claude Desktop、Cursor）中添加 mcpServers 条目，设置 command 为 uvx，args 为 ["mcp-grafana"]，并在 env 中提供 GRAFANA_URL 和 GRAFANA_SERVICE_ACCOUNT_TOKEN（Grafana Cloud 用户将 GRAFANA_URL 替换为实例地址，如 https://<instance>.grafana.net）。4. 也可使用 Docker 镜像 docker.io/grafana/mcp-grafana 以 stdio 方式运行，或直接连接托管的远程端点 https://mcp.grafana.com/mcp（streamable-http，可通过 X-Grafana-URL 请求头指定 Grafana Cloud 实例）。5. 按需通过 --enabled-tools 或 --disable-<category> 标志启用/禁用工具类别，使用 --disable-write 运行只读模式。
claude_desktop_config.json
{"mcpServers":{"grafana":{"command":"uvx","args":["mcp-grafana"],"env":{"GRAFANA_URL":"http://localhost:3000","GRAFANA_SERVICE_ACCOUNT_TOKEN":"<your service account token>"}}}}
选型与风险
不适合谁
- 不使用 Grafana 生态（无 Prometheus/Loki/等数据源接入）的团队
- 需要完全离线、无外部网络依赖的环境（远程端点和部分数据源查询需要网络访问）
- 对写权限高度敏感且不愿意配置精细 RBAC 范围的场景（默认 Editor 角色权限较宽泛）
所需权限
- GRAFANA_URL（必需）：目标 Grafana 实例地址
- GRAFANA_SERVICE_ACCOUNT_TOKEN 或 GRAFANA_USERNAME/GRAFANA_PASSWORD：用于身份验证的凭据（服务账号令牌为敏感信息）
- 按工具类别所需的 Grafana RBAC 权限，如 dashboards:read/write、datasources:query、alert.rules:read/write、annotations:read/write 等，或简化使用内置 Editor 角色
- Grafana Incident/Sift 使用基本角色（Viewer 读、Editor 写）而非细粒度 RBAC
- 可选 GRAFANA_ORG_ID 或 X-Grafana-Org-Id 头以指定多组织场景
- 可选 GRAFANA_EXTRA_HEADERS 和 GRAFANA_FORWARD_HEADERS，用于附加或转发 HTTP 头（如 Cookie）到 Grafana API
风险与副作用
- 服务账号令牌、密码等凭据以环境变量或请求头形式存在，需妥善保管，避免泄露
- 写工具（update_dashboard、alerting_manage_rules、create_incident、create_annotation、create_snapshot 等）可直接修改或删除 Grafana 中的仪表盘、告警和事件数据，误用可能造成生产配置损坏
- 若使用内置 Editor 角色简化权限配置，权限范围较宽，超出最小必要权限原则
- 获取完整仪表盘 JSON（get_dashboard_by_uid、update_dashboard）可能占用大量上下文窗口，且可能包含仪表盘中的敏感查询或变量信息
- GRAFANA_FORWARD_HEADERS 转发请求头（如 Cookie）时如配置不当可能带来会话信息泄露风险
- 远程托管端点 https://mcp.grafana.com/mcp 是第三方托管服务，通过它访问 Grafana Cloud 实例意味着请求经过该服务中转
- SSE/streamable-http 传输在配置不当（如 --allowed-hosts 或 --allowed-origins 设置为 * 且暴露在不受信网络）时存在 DNS 重绑定等风险
常见排障
- 确认 GRAFANA_URL 格式正确且服务器可达；Grafana Cloud 用户使用 https://<instance>.grafana.net
- 若某些工具报权限错误，检查服务账号令牌对应的 RBAC 权限和作用域（scope）是否覆盖所需操作，或临时使用 Editor 角色排查是否为权限问题
- 数据源相关功能异常时，确认 Grafana 版本不低于 9.0
- 工具未出现在客户端中时，检查是否被默认禁用类别（如 admin、clickhouse、cloudwatch、snowflake 等）覆盖，需通过 --enabled-tools 显式启用
- SSE/streamable-http 请求收到 403 时，检查 --allowed-hosts 与 --allowed-origins 配置是否包含请求的 Host/Origin
- 使用 --debug 标志开启详细 HTTP 请求/响应日志以排查连接问题
- Kubernetes 环境中令牌轮换未生效时，确认使用的是 GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE 而非内联令牌，并检查挂载的 Secret 是否更新
- get_panel_image 渲染失败时，确认目标 Grafana 实例已安装并配置 Grafana Image Renderer 服务
使用场景
让 AI 助手排查生产告警：查询 Prometheus/Loki 指标与日志、运行 Sift 根因分析、创建 Grafana Incident
自然语言驱动的仪表盘检索与轻量编辑，无需在 Grafana UI 中手动查找面板
跨多种数据源（Prometheus、Loki、ClickHouse、CloudWatch、Athena、Snowflake 等）统一查询和探索
自动生成指向具体仪表盘、面板或 Explore 视图的深层链接，用于报告或工单
支持客户端
Claude Desktop完整支持
Cursor完整支持