AI导哈

Grafana仪表板管理协议

Grafana MCP是一个用于在多集群环境中发现、编辑和测试Grafana仪表板和文件夹的协议服务器，提供标签保护和选择性修改功能。

  • by christian-schlichtherle
  • Python
  • 本地部署
  • 4 星标
  • 更新于
在 GitHub 查看 christian-schlichtherle/grafana-mcp

使用说明

Grafana MCP

该存储库提供了一个MCP（模型上下文协议）服务器，用于全面的发现、编辑和测试 一个或多个Grafana集群中的仪表板和文件夹。 它的 安全模型 基于标签和文件夹。

快速开始

# Install and run with zero configuration (uses localhost:3000 by default)
uv sync
python main.py

# That's it! The server is ready to use with your local Grafana instance.

特性

  • 仪表板保护：在创建Grafana仪表板时，MCP服务器会标记它们以将自己标记为源
  • 选择性修改：只能更新或删除具有所需保护标签的仪表板
  • 无限制阅读：阅读仪表板没有限制，允许通过复制来增强现有仪表板
  • 文件夹限制：对特定文件夹和子文件夹的可配置访问控制
  • 多集群支持：跨多个Grafana实例管理仪表板
  • 综合搜索：完全支持Grafana的搜索API和过滤选项

可用的MCP工具

发现

发现和探索集群中的Grafana资源。

群集管理

  • list_clusters() -列出所有已配置的Grafana集群名称
  • check_cluster_health(cluster: str) -检查Grafana集群的运行状况和连接性

搜索操作

  • search(cluster: str, *, query: str = "", tags: list = [], starred: bool = False, folder_uids: list = [], dashboard_uids: list = [], dashboard_ids: list = [], type: str = "", limit: int = 1000, page: int = 1) -使用全面的筛选选项搜索仪表板和文件夹

仪表板发现

  • read_dashboard(cluster: str, dashboard_uid: str) -读取任何仪表板配置和元数据（无限制）
  • inspect_dashboard(cluster: str, dashboard_uid: str) -仪表板面板、变量、数据源和布局的详细结构分析

文件夹发现

  • list_folders(cluster: str, *, parent_uid: str = "") -列出文件夹，可选择在父文件夹下
  • get_folder(cluster: str, folder_uid: str) -获取详细的文件夹信息，包括层次结构和权限

数据源发现

  • list_datasources(cluster: str) -列出集群中的所有数据源，包括名称、类型、UID和元数据

编辑

使用安全控制创建、修改和管理Grafana资源。

仪表板管理

  • create_dashboard(cluster: str, dashboard_json: dict, *, folder_uid: str = "") -创建带有自动保护标签的新仪表板
  • update_dashboard(cluster: str, dashboard_uid: str, dashboard_json: dict) -更新现有仪表板（需要保护标签）
  • delete_dashboard(cluster: str, dashboard_uid: str) -删除仪表板（需要保护标签）
  • copy_dashboard(source_cluster: str, source_uid: str, new_title: str, *, target_cluster: str = "", folder_uid: str = "", target_uid: str = "") -具有智能UID处理和自动覆盖功能的复制仪表板

文件夹管理

  • create_folder(cluster: str, title: str, *, parent_uid: str = "") -创建新文件夹，可选为子文件夹
  • update_folder(cluster: str, folder_uid: str, title: str, *, parent_uid: str = "") -更新/重命名/移动文件夹到不同的父文件夹
  • delete_folder(cluster: str, folder_uid: str, *, force_delete_rules: bool = False) -使用可选的警报规则清理删除文件夹

测试

验证、测试和分析仪表板质量和数据准确性。

验证和质量保证

  • validate_dashboard(cluster: str, dashboard_uid: str) -全面的模式验证和最佳实践检查
  • compare_dashboards(cluster: str, dashboard_uid_a: str, dashboard_uid_b: str, *, compare_cluster_b: str = "") -比较两个显示结构和配置差异的仪表板

数据验证和测试

  • snapshot_dashboard(cluster: str, dashboard_uid: str, *, snapshot_name: str = "", expires_hours: int = 24, time_from: str = "now-6h", time_to: str = "now") -使用当前数据创建快照以供检查和测试
  • test_panel_render(cluster: str, dashboard_uid: str, panel_id: int, *, width: int = 1000, height: int = 500, time_from: str = "now-6h", time_to: str = "now", save_to_file: str = "") -将面板渲染为PNG以进行视觉验证

配置

环境变量

使用以下环境变量配置MCP服务器：

# Cluster URLs (space-separated key=value pairs, defaults to "localhost=http://localhost:3000")
export GRAFANA_CLUSTERS="localhost=http://localhost:3000 dev=https://grafana.dev.example.com prod=https://grafana.prod.example.com"

# Cluster API tokens (space-separated key=value pairs, optional)
# Only required for clusters that need authentication
export GRAFANA_TOKENS="dev=glsa_yyy prod=glsa_zzz"  # Note: localhost has no token (unauthenticated)

# Protection labels (space-separated, defaults to "MCP")
export GRAFANA_LABELS="MCP Claude"

# Folder restriction (defaults to "/" for root access)
export GRAFANA_FOLDER=/MCP

无身份验证的本地开发

对于本地开发，您可以在Docker容器中运行Grafana而无需身份验证：

# Run Grafana without authentication
docker run -d \
  -p 3000:3000 \
  -e "GF_AUTH_ANONYMOUS_ENABLED=true" \
  -e "GF_AUTH_ANONYMOUS_ORG_ROLE=Admin" \
  -e "GF_AUTH_BASIC_ENABLED=false" \
  --name grafana \
  grafana/grafana:latest

# Configure MCP server for unauthenticated local access
export GRAFANA_CLUSTERS="localhost=http://localhost:3000"
# No GRAFANA_TOKENS needed!

# Or use the default configuration (no environment variables needed!)
# This defaults to localhost=http://localhost:3000 without authentication

# Run the MCP server
python main.py

混合身份验证环境

您可以混合使用经过身份验证和未经身份验证的集群：

# Local without auth, production with auth
export GRAFANA_CLUSTERS="localhost=http://localhost:3000 prod=https://grafana.prod.com"
export GRAFANA_TOKENS="prod=glsa_abc123"  # Only prod needs a token

身份验证设置（适用于生产集群）

对于生产或经过身份验证的Grafana集群，您需要创建服务帐户令牌。建议使用服务帐户通过Grafana的HTTP API进行身份验证（不推荐使用API密钥）。

备注：如果您只使用本地未经身份验证的Grafana实例，请跳过此部分。

通过Grafana UI创建服务帐户令牌

  1. 创建服务帐户:

    • 引导到 行政 → 用户和访问 → 服务帐户
    • 点击 “添加服务帐户”
    • 输入a 显示名称 （例如，“MCP服务器”）
    • 选择合适的 角色: Viewer, Editor，或 Admin
    • 点击 “创建”

  2. 生成令牌:

    • 选择您新创建的服务帐户
    • 点击 “添加服务帐户令牌”
    • 输入a 显示名称 对于令牌
    • 集 有效期至 （或选择“无过期”）
    • 点击 “生成令牌”
    • 重要：立即复制并保存令牌-它只显示一次！

通过API创建服务帐户令牌

# Create service account
curl -X POST -H "Content-Type: application/json" \
  -d '{"name": "mcp-server", "role": "Editor"}' \
  http://admin:admin@localhost:3000/api/serviceaccounts

# Create token for the service account (use ID from previous response)
curl -X POST -H "Content-Type: application/json" \
  -d '{"name": "mcp-token"}' \
  http://admin:admin@localhost:3000/api/serviceaccounts/{id}/tokens

使用代币

令牌应前缀为 glsa_ 并用于 GRAFANA_TOKENS 环境变量：

export GRAFANA_TOKENS="prod=glsa_abc123def456 dev=glsa_xyz789uvw012"

请求中的身份验证

MCP服务器会自动将Bearer令牌添加到所有请求中：

Authorization: Bearer glsa_abc123def456

有关更多信息，请参阅 Grafana关于服务账户的官方文件.

安装与使用

  1. 安装依赖项:

    uv sync
# or
pip install -e .

  2. 设置环境变量 （见上文配置部分）

  3. 运行MCP服务器:

    python main.py

服务器将验证您的配置并启动MCP服务器，使MCP客户端可以使用所有工具。

示例用法

# List all configured clusters
clusters = list_clusters()
# Returns: ["localhost", "prod"]

# Explore folder hierarchy
root_folders = list_folders("prod")  # List root-level folders
subfolders = list_folders("prod", parent_uid="folder123")  # List subfolders

# Search for dashboards and folders
dashboards = search("prod", query="monitoring", tags=["production"])
folders_only = search("prod", type="dash-folder", query="team")
dashboards_only = search("prod", type="dash-db", starred=True)

# Create and manage folders
folder = create_folder("prod", "Team Alpha", parent_uid="parent123")
updated = update_folder("prod", "folder123", "New Name", parent_uid="new_parent")

# Copy a dashboard into a specific folder
new_dash = copy_dashboard("prod", "abc123def", "My New Dashboard", folder_uid="folder123")

# Create a dashboard with protection labels automatically added
result = create_dashboard("prod", {
    "title": "Test Dashboard",
    "panels": [...],
    "tags": ["custom"]  # MCP labels will be automatically added
}, folder_uid="folder123")

安全模型

  • 基于标签的保护：此MCP服务器创建的仪表板会自动标记保护标签
  • 选择性操作：只能更新或删除具有所需标签的仪表板
  • 文件夹限制：操作可以限制在特定的文件夹层次结构中
  • 基于令牌的身份验证：使用安全服务帐户令牌，而不是不推荐使用的API密钥
  • 无覆盖：创建仪表板可防止意外覆盖现有仪表板

相关 MCP