Grafana MCP Server 项目详细介绍

项目概述

Grafana MCP Server 是一个基于模型上下文协议 (Model Context Protocol, MCP) 的服务器，专为与 Grafana 实例及其周边生态系统集成而设计。该项目为 AI 代理（如 Claude Desktop）提供了访问和操作 Grafana 各种功能的能力。

核心功能特性

仪表板管理

搜索仪表板：快速检索和定位特定的仪表板
获取仪表板：通过 UID 获取完整的仪表板配置
更新/创建仪表板：动态修改或创建新的仪表板（需要注意上下文窗口限制）

数据源集成

数据源管理：列出和获取数据源信息
多数据源查询支持：
- Prometheus：执行 PromQL 查询，获取指标数据
- Loki：执行 LogQL 查询，检索日志数据
- Tempo：分布式追踪数据查询
- Pyroscope：性能分析数据查询

元数据查询

Prometheus 元数据：获取指标元数据、指标名称、标签名称和标签值
Loki 元数据：获取日志标签名称、标签值和统计信息

事件和告警管理

事件管理：搜索、创建、更新和关闭事件
告警规则：列出和获取告警规则信息，获取告警状态
联系点管理：列出、创建和修改告警联系点

Grafana OnCall 集成

排班管理：列出和管理值班计划
值班信息：获取值班详情和当前值班用户
团队和用户管理：管理团队和用户信息
告警组管理：列出告警组

Sift 调查功能

智能调查：启动 Sift 调查并查看结果
调查管理：创建、列出和获取调查信息
分析功能：获取调查分析结果
错误模式识别：在日志中查找错误模式
性能分析：识别慢请求

工具配置

该项目提供了灵活的工具配置选项，您可以选择启用或禁用特定的功能类别：

工具名称	分类	描述
`search_dashboards`	Search	搜索仪表板
`get_dashboard_by_uid`	Dashboard	通过 UID 获取仪表板
`update_dashboard`	Dashboard	更新或创建新仪表板
`list_datasources`	Datasources	列出数据源
`query_prometheus`	Prometheus	执行 Prometheus 查询
`query_loki_logs`	Loki	查询和检索日志
`list_incidents`	Incident	列出事件
`list_alert_rules`	Alerting	列出告警规则
`list_oncall_schedules`	OnCall	列出 OnCall 排班计划
`find_error_pattern_logs`	Sift	查找错误模式

使用 --disable-<category> 标志可以禁用特定的工具类别。例如，使用 --disable-oncall 可以禁用 OnCall 相关工具。

安装和配置

安装方式

1. Docker 镜像

docker pull mcp/grafana
docker run -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_API_KEY=<your_token> mcp/grafana

2. 下载二进制文件

从 releases 页面下载最新版本并放置在 $PATH 目录中。

3. 源码编译

GOBIN="$HOME/go/bin" go install github.com/grafana/mcp-grafana/cmd/mcp-grafana@latest

配置设置

先决条件

在 Grafana 中创建服务账户，并分配足够的权限
生成服务账户令牌

Claude Desktop 配置

使用二进制文件：

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

使用 Docker：

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run", "--rm", "-p", "8000:8000",
        "-e", "GRAFANA_URL", "-e", "GRAFANA_API_KEY",
        "mcp/grafana"
      ],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_API_KEY": "<your service account token>"
      }
    }
  }
}

调试模式

通过添加 -debug 标志启用调试模式，可以提供详细的 HTTP 请求和响应日志：

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

开发和测试

开发环境设置

# 运行服务器
make run

# 构建 Docker 镜像
make build-image

# 运行 Docker 容器
docker run -it --rm -p 8000:8000 mcp-grafana:latest

测试类型

单元测试

make test-unit
# 或者
make test

集成测试

# 需要启动 Docker 容器
make test-integration

云测试

# 需要云 Grafana 实例和凭证
make test-cloud

完整测试

# 启动本地 Grafana 实例
docker-compose up -d

# 运行所有测试
make test-all

代码质量

代码检查

make lint

JSON Schema 检查

该项目包含自定义的 linter，用于检查 jsonschema 结构标签中未转义的逗号：

make lint-jsonschema

技术架构

编程语言：Go
协议：Model Context Protocol (MCP)
通信方式：stdin/stdout 或 SSE (Server-Sent Events)
支持的客户端：Claude Desktop 等 MCP 兼容客户端

使用场景

AI 驱动的监控：让 AI 代理能够智能地查询和分析监控数据
自动化运维：通过 AI 自动创建和管理仪表板、告警规则
智能事件响应：利用 AI 分析日志和指标，快速定位和解决问题
数据洞察：让 AI 帮助从复杂的监控数据中提取有价值的信息

这个项目代表了 AI 与传统监控工具集成的新趋势，为开发者提供了一个强大的桥梁，连接人工智能助手和 Grafana 生态系统。