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

配置设置

先决条件

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

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 兼容客户端

使用场景

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

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