Grafana MCP Server

Grafana MCP

此代码库提供一个 MCP（Model Context Protocol）服务，可全面发现、编辑和测试一个或多个 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. 创建服务账号：

   • 前往 Administration → Users and access → Service Accounts
   • 点击 "Add service account"
   • 输入 Display name（例如，“MCP Server”）
   • 选择合适的 Role：Viewer、Editor 或 Admin
   • 点击 "Create"

2. 生成令牌：

   • 选择刚创建的服务账号
   • 点击 "Add service account token"
   • 输入令牌的 Display name
   • 设置 Expiration date（或选择 "No expiration"）
   • 点击 "Generate token"
   • 重要：立即复制并保存令牌——它只会显示一次！

通过 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 密钥
• 不覆盖：创建仪表板时会阻止意外覆盖现有仪表板