Grafana MCP Server

Grafana MCP

このリポジトリは、1 つ以上の Grafana クラスターにあるダッシュボードとフォルダーを包括的に検索、編集、テストするための MCP（Model Context Protocol）サーバーを提供します。 セキュリティモデルは、ラベルとフォルダーに基づいています。

クイックスタート

# 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 = "") - 2 つのダッシュボードを比較し、構造と設定の違いを表示します

データの検証とテスト

• 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 キーではなく、安全なサービスアカウントトークンを使用します
• 上書きなし：ダッシュボードの作成時に、既存のダッシュボードを誤って上書きすることを防ぎます