mcp-grafana

mcp-grafana

Grafana 向けの、デフォルトで安全な Model Context Protocol サーバーです。エージェントが Grafana を調査・操作できます。ダッシュボードの検索、ダッシュボード JSON モデルの読み取り、データソース（Prometheus／Loki／SQL）の一覧表示とクエリ実行、アラートルールやアノテーションの確認に加え、より高いモードではダッシュボードやフォルダーの作成・更新、アノテーションの書き込み、削除を行えます。

Dockndevai MCP サーバースイートの一部であり、すべてのサーバーで共通のガバナンスモデルを採用しています。

エージェントに提供する機能

サーバーは読み取り専用で起動します（デフォルトで安全を参照）。より高い機能を持つツールは、モードを引き上げた場合にのみ登録されます。

ツール	用途	必要なモード
get_health	インスタンスの稼働状況とバージョンを確認する	読み取り専用
search	名前／タグでダッシュボードやフォルダーを検索する（UID を取得）	読み取り専用
list_dashboards / list_folders	ダッシュボード／フォルダーを一覧表示する	読み取り専用
get_dashboard	ダッシュボードの完全な JSON モデルとメタデータを取得する	読み取り専用
list_datasources / get_datasource	データソースを取得する（シークレットはマスキングされます）	読み取り専用
query_datasource	統合クエリ API 経由で PromQL／LogQL／SQL を実行する	読み取り専用
list_alert_rules	Grafana 管理のアラートルールを取得する	読み取り専用
list_annotations	グラフ上に表示されるイベントを取得する	読み取り専用
create_or_update_dashboard	ダッシュボードを作成または更新する（バージョン管理され、元に戻せます）	読み書き
create_folder	フォルダーを作成する	読み書き
create_annotation	グラフにデプロイ／インシデントを記録する	読み書き
delete_dashboard / delete_folder / delete_annotation	削除する（取り消し不可）	管理者 + GRAFANA_ALLOW_DELETE

インストール

npx -y @dockndevai/mcp-grafana

Grafana のサービスアカウントトークンが必要です（Administration → Service accounts → Add service account → Add token）。動作する範囲で最小限のロールを付与してください。読み取り専用の場合は Viewer、作成／更新の場合は Editor、削除が必要な場合に限り Admin を使用します。

設定

{
  "mcpServers": {
    "grafana": {
      "command": "npx",
      "args": ["-y", "@dockndevai/mcp-grafana"],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_TOKEN": "glsa_...",
        "GRAFANA_MODE": "read-only"
      }
    }
  }
}

Claude Code／Cursor／Codex／VS Code／Windsurf の設定例については docs/CLIENTS.md を、サポートされているすべての変数については .env.example を参照してください。

デフォルトで安全

アクセスモデルは src/security.ts で適用されます。サービスアカウントトークン自体のロールに加え、多層防御を行います。

• GRAFANA_MODE — read-only（デフォルト）→ read-write → admin。モードで機能が許可されている場合にのみ、ツールが登録されます。読み取り専用モードでは11個の読み取りツールが利用でき、編集には read-write、削除には admin が必要です。
• GRAFANA_ALLOW_DELETE — 削除は取り消せないため、admin モードに加えて、このフラグも必要です。
• GRAFANA_FOLDER_ALLOWLIST / GRAFANA_PROTECTED_FOLDERS — 書き込み可能なフォルダーを制限します。読み取りは可能でも変更や削除はできないフォルダー（例：production）を指定します。
• GRAFANA_DATASOURCE_ALLOWLIST — query_datasource がアクセスできるデータソースを制限します。
• GRAFANA_DRY_RUN — 書き込みを実行せずに検証し、ログに記録します。
• GRAFANA_AUDIT_LOG — 保護対象の操作ごとに、stderr に JSON 形式の監査ログを出力します（デフォルトで有効）。
• 対話型の確認 — クライアントが MCP のエリシテーションに対応している場合、ダッシュボード／フォルダー／アノテーションを削除する前に、人間に承認を求めます。エリシテーションに対応していないクライアントでは、代わりに GRAFANA_ALLOW_DELETE による制限が適用されます。
• シークレットは一切返されません — データソースの secureJsonData、パスワード、トークンは、すべてのレスポンスから除外されます。

SECURITY.md を参照してください。

ダッシュボードとクエリの操作

ダッシュボードの JSON モデル、パネル／ターゲットの形式、PromQL／LogQL／SQL のクエリパターン、フォルダーの構成、安全な編集に関する規約は、同梱のスキルに記載されています：.claude/skills/grafana-dashboards-and-queries/SKILL.md。このスキルを読み込んだエージェントは、毎回説明を受けなくても、一貫した基準に沿ってダッシュボードを作成・編集できます。

開発

npm install
npm run build
GRAFANA_URL=http://localhost:3000 GRAFANA_TOKEN=glsa_… node dist/index.js
# introspect without a live Grafana:
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | GRAFANA_TOKEN=x node dist/index.js

ライセンス

MIT