grafana-mcp

Grafana APIの一部をMCP（Model Context Protocol）サーバーとして公開し、自然言語によるログクエリに焦点を当てています。主な目的は、「過去30分間のapiサービスのログを表示して」と言うだけで、LogQLやラベル、データソースUIDを手動で操作することなく、実際のログ行を取得することです。

ログデータソース、Lokiラベル、およびサービス名からホスティングデータソース/ラベルへのマッピングはディスクにキャッシュされるため、繰り返し呼び出しでは冗長なラベルスキャンがスキップされます。

한국어 문서 / Korean README

インストールとセットアップ

npx (インストール不要)

~/.mcp.json に以下を追加します。

{
  "mcpServers": {
    "grafana": {
      "command": "npx",
      "args": ["@seungje.jun/grafana-mcp"],
      "env": {
        "GRAFANA_URL": "https://grafana.example.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "glsa_xxx"
      }
    }
  }
}

ソースからビルド

git clone https://github.com/ninanung/grafana-mcp.git
cd grafana-mcp
npm install
npm run build

{
  "mcpServers": {
    "grafana": {
      "command": "node",
      "args": ["/path/to/grafana-mcp/dist/cli.js"],
      "env": {
        "GRAFANA_URL": "https://grafana.example.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "glsa_xxx"
      }
    }
  }
}

Claude Codeを再起動してMCPツールを有効にします。

認証

以下のいずれかが必要です。以下の順序でチェックされ、最初に見つかったものが使用されます。

すべてのベアラートークンは Authorization: Bearer <token> として送信されます。サーバーはトークンの種類を問わず、設定されているものを選択します。

環境変数

Related MCP server: Log Analyzer MCP Server

ツール

使用例

MCPクライアントによって調整される典型的な自然言語フロー:

1. ユーザー: 「過去30分間のapiサービスのエラーログを表示して。」

2. service: "api", level: "error", time_from: "now-30m" を指定して query_logs を実行 → サーバーは service="api" ラベルを所有するLokiデータソースを自動検出し、LogQLを実行します。

3. (初回呼び出し) サービス → データソース/ラベルのマッピングがキャッシュに保存されます。以降の呼び出しでは検出ステップがスキップされます。

4. ユーザー: 「それらのエラーをパターン別に要約して。」 → output: "summarize" を指定した同じ呼び出しで、パターン別にグループ化されたカウントが返されます。

5. ユーザー: 「他にどんなサービスがある？」 → list_services がサービスリスト全体を返します。

サービス名にタイプミスがある場合、query_logs は近い一致を表示します (例: Did you mean: checkout, checkout-api?)。

自動検出の仕組み

query_logs はターゲットのデータソースとラベルを独自に選択します:

1. すべてのデータソースをログタイプ (Loki/ES/CloudWatch/OpenSearch/Splunk) に絞り込みます。

2. 各Lokiデータソースについて、/loki/api/v1/labels を取得し、一般的なサービスラベル候補 (service, service_name, app, app_name, application, container, job) を最初に走査し、次に残りのラベルを走査します。

3. 各候補ラベルについて、その値を取得し、要求された service 名がそのリストに含まれているかを確認します。

4. ちょうど1つの (datasource, label) ペアが一致する場合、それを使用します。複数一致する場合は、区別するために datasource_uid を要求します。一致しない場合は、近い名前の提案を返します。

5. 解決された (service → ds_uid, label) はキャッシュされます。refresh: true または refresh_log_cache で再検出を強制できます。

自動検出は現在Lokiのみをサポートしています。Elasticsearch / CloudWatch / Splunkデータソースの場合は、datasource_uid と service_label を明示的に渡してください (LogQL固有のフィルターは適用されません)。

出力モード

query_logs は output を受け入れます:

• raw (デフォルト): <ISO timestamp> <log line> — ターミナルで直接読むのに適しています。

• summarize: 行を正規化されたパターン (数値 → N, UUID → UUID) でグループ化し、カウントとパターンごとのサンプルを表示します。行がノイズの多い場合や多すぎる場合に使用します。

• json: 構造化オブジェクト { ts, line, labels } — 下流のツール用。

キャッシュ

• ログキャッシュ: ~/.grafana-mcp/log-cache.json に永続化されます。GrafanaベースURLごとにキーが付けられるため、複数のインスタンスが競合することはありません。

• 各カテゴリには独自のTTL (データソース / ラベル / ラベル値 / サービス解決) があります — 上記の環境変数テーブルを参照してください。

• 後で失敗したキャッシュされたサービス解決 (例: ラベル名が変更された) は自動的に無効化されるため、次の呼び出しで再検出されます。

• get_log_cache で確認、refresh_log_cache でクリア、export_log_cache / import_log_cache でチームメイトと共有できます。

キャッシュの場所とリセット

キャッシュファイルはプレーンなJSONドキュメントであり、手動で確認、編集、バックアップしても安全です。

安全性と制約

• 読み取り専用: サーバーはGrafanaの状態を変更するエンドポイントを公開しません。ダッシュボード/データソースのCRUDやアラートの変更は行われません。

• Stdioログ: すべてのログはstderrに出力され、MCP stdioチャネルをクリーンに保ちます。

• TLSスキップ: GRAFANA_TLS_SKIP_VERIFY=true はプロセス全体で NODE_TLS_REJECT_UNAUTHORIZED=0 を設定します。信頼できるネットワーク内の自己署名Grafanaに対してのみ使用してください。

• シークレットのログ記録なし: 認証トークンは監査ログに書き込まれません。

ライセンス

MIT