Grafana MCP

grafana-mcp

プロジェクト単位の Grafana MCP サーバー — AI コーディングエージェントに、プロジェクトごとのコンテキストと test/prod 環境の切り替え機能を備えた、Loki ログ、Prometheus メトリクス、Tempo トレース、アラートへの読み取り専用アクセスを提供します。依存関係ゼロの単一 TypeScript ファイルで、bun から直接実行できます。

AI 编码 Agent（Claude Code / Cursor / …）
        │  MCP (stdio)
        ▼
   grafana-mcp ──读──▶ .mcp.json env / .grafana.json / ~/.zshrc（凭据与项目上下文）
        │  HTTP（只读查询 API）
        ▼
   Grafana ──▶ Loki（日志）/ Prometheus（指标）/ Tempo（链路）/ Alerts（告警）

解決する問題

業務システムを日常的に開発する際、テスト段階では QA からのフィードバックにある問題をすばやく特定し、本番環境では機能のバグやパフォーマンスのボトルネックを迅速に調査する必要があります。これらの証拠はすべて Grafana のエコシステム（Loki ログ、Prometheus メトリクス、Tempo トレース）にあります。エージェントがコードの作成やバグ修正と同時に、こうしたコンテキストを直接調べられるようにすれば、問題の特定効率と正確性が大きく向上します。しかし、汎用的な MCP で Grafana API をラップするだけでは、実際には次の 3 つの障壁があります。

問題点	本実装での解決策
プロジェクトのセッションごとに「Grafana 上で自分たちのアプリが何と呼ばれているか」を口頭でエージェントに伝える必要があり、誤認しやすい	プロジェクトのルートに .grafana.json を置くか、.mcp.json の env で設定します（app、namespace、デフォルト環境）。エージェントは project_context を一度呼び出すだけで、前提を共有できます
test/prod の 2 つの環境で認証情報を分ける必要がありますが、MCP サーバーはクライアントによって起動される非対話型シェルのため、.zshrc を source せず、環境変数を読み取れません	次の 3 つから選べます。① .mcp.json の env から GRAFANA_{ENV}_* を直接渡す（グローバルな依存関係ゼロ）② サーバー起動時に ~/.zshrc / ~/.zshenv のファイルテキストを解析する ③ グローバル設定ファイルを使う
複数のデータソースがある場合、「種類ごとに最初のものを取得」すると誤ったものを選びやすい	明示的に設定されたデータソース UID を優先し、環境ごとの指定にも対応します

免責事項

1. 非公式プロジェクト：本リポジトリは Grafana Labs とは無関係です。Grafana、Loki、Prometheus、Tempo はそれぞれの権利者の商標です。
2. 免責：本ソフトウェアは「現状のまま」提供されます。使用者は、対象の Grafana インスタンスへのアクセスが許可されていることを自ら確認し、所属組織のデータセキュリティおよび監査に関する規定を遵守してください。ログやメトリクスの出力には業務上の機密情報が含まれる可能性があります。クエリ結果を共有する前に、コンプライアンス上の境界を自ら判断してください。作者は、規定に反する使用およびその結果について責任を負いません。
3. 読み取り専用の範囲：10 個のツールはすべてクエリ用で、書き込み操作はありません。エージェントには Viewer ロールの専用アカウント（最小権限）を設定し、管理者の認証情報を使い回さないことをおすすめします。

クイックスタート

前提条件：ローカル環境に bun がインストールされていること（curl -fsSL https://bun.sh/install | bash）。プロジェクトに npm 依存関係はないため、npm install は不要です。

方法 1：プロジェクト単位で完結する設定（おすすめ — グローバルな依存関係ゼロ）

すべての情報（test/prod の両環境の URL、認証情報、データソース UID、プロジェクトの app 名）をプロジェクトの .mcp.json に記述し、~/.zshrc には依存しません。別のマシンに移る場合は、.mcp.json をコピーするだけです。

{
  "mcpServers": {
    "grafana": {
      "command": "bunx",
      "args": ["grafana-mcp"],
      "env": {
        "GRAFANA_ENV": "test",
        "GRAFANA_APP": "my-app",
        "GRAFANA_NAMESPACE": "my-namespace",

        "GRAFANA_TEST_URL": "https://grafana.test.example.com",
        "GRAFANA_TEST_USER": "viewer",
        "GRAFANA_TEST_PASSWORD": "********",
        "GRAFANA_TEST_LOKI_DATASOURCE": "loki-uid-here",
        "GRAFANA_TEST_PROMETHEUS_DATASOURCE": "prom-uid-here",

        "GRAFANA_PROD_URL": "https://grafana.prod.example.com",
        "GRAFANA_PROD_USER": "viewer",
        "GRAFANA_PROD_PASSWORD": "********",
        "GRAFANA_PROD_LOKI_DATASOURCE": "loki-uid-prod",
        "GRAFANA_PROD_PROMETHEUS_DATASOURCE": "prom-uid-prod"
      }
    }
  }
}

設定後：

• project_context は現在の環境、利用可能な環境の一覧、プロジェクトの app などの情報を自動的に表示します
• switch_environment で test/prod を切り替えられます（現在のセッションにのみ適用されます）
• loki_query は app="my-app" ラベルを自動的に追加します（injectApp=false で無効化できます）

⚠️ .mcp.json には認証情報が平文で含まれるため、必ず .gitignore に追加してください。

方法 2：zshrc のグローバル認証情報 + プロジェクト単位のコンテキスト

複数のプロジェクトで同じ Grafana 認証情報を共有する場合に適しています。認証情報は ~/.zshrc に一度設定し、各プロジェクトではプロジェクトのコンテキストのみを設定します。

プロジェクトの .mcp.json（プロジェクトのコンテキストのみを設定し、認証情報は含めません）：

{
  "mcpServers": {
    "grafana": {
      "command": "bunx",
      "args": ["grafana-mcp"],
      "env": {
        "GRAFANA_ENV": "test",
        "GRAFANA_APP": "my-app"
      }
    }
  }
}

または、プロジェクトの .grafana.json（より多くの情報を設定でき、エージェントから参照・解釈できます）：

{
  "defaultEnv": "test",
  "app": "my-app",
  "appLabel": "app",
  "namespace": "my-namespace",
  "notes": "本项目日志标签 app=my-app；查指标时 pod 前缀为 my-app-"
}

フィールド	説明
defaultEnv	デフォルト環境（test / prod / カスタム）
app	Loki におけるアプリの app ラベル値。loki_query がクエリセレクターに自動的に追加します
appLabel	app ラベル名。デフォルトは app です
namespace	デフォルトの namespace。エージェントの参考情報として使用されます
notes	自由記述のメモ。project_context がそのままエージェントに渡します
environments.{env}.url	該当環境の Grafana URL（zshrc 内の同名の変数を上書きします）
environments.{env}.user	該当環境のユーザー名
environments.{env}.password	該当環境のパスワード
environments.{env}.app	該当環境の app ラベル値（同一プロジェクトで test/prod の名前が異なる場合に使用し、トップレベルの app より優先されます）
environments.{env}.appLabel	該当環境の app ラベル名。デフォルトは app です
environments.{env}.datasources	環境ごとのデータソース UID（loki/prometheus/tempo）

⚠️ .grafana.json の notes と environments には機密情報が含まれる可能性があります。.gitignore に追加することをおすすめします。

認証情報の取得元（3 つのソースを優先順位に従って統合）

进程环境变量（.mcp.json env：GRAFANA_{ENV}_URL 等按环境，或 GRAFANA_URL 直连）
  → 项目 .grafana.json 的 environments.{env} 字段
    → 全局配置 ~/.config/grafana-mcp/config.json（可选，适合无 .zshrc 的机器）
      → ~/.zshrc + ~/.zshenv 文本解析（适合全机统一配置）

シェル環境に依存しません：MCP サーバーはクライアントによって起動される非対話型・非ログインシェルであり、rc ファイルを source しません。本実装は rc ファイルのテキストを直接解析するか、プロセスの環境変数から読み取ります。これは回避策ではなく、仕様です。

クローンして使用する

クローンして使用する場合：

git clone https://github.com/itzhouq/grafana-mcp.git && cd grafana-mcp
bun run index.ts          # stdio JSON-RPC，接入任意 MCP 客户端

.mcp.json には、"command": "bun", "args": ["run", "/path/to/grafana-mcp/index.ts"] と記述します。

ツール一覧

ツール	説明
project_context	調査前に必ず呼び出してください：有効な環境、利用可能な環境、プロジェクトの App/namespace、データソース UID、設定元（パスワードはマスキングして出力）
switch_environment	test/prod を切り替えます（現在のセッションにのみ適用）。新しい環境のコンテキストを返します
loki_query	LogQL によるログクエリ。プロジェクトに app が設定されている場合、セレクターを自動的に追加します（injectApp=false で無効化できます）
loki_labels	Loki のラベル名を一覧表示するか、特定のラベルのすべての値を調べます（例：現在の環境に app 名が存在するかを確認）
prom_query	PromQL による範囲クエリ
prom_instant	PromQL によるインスタントクエリ
tempo_search	TraceQL によるトレース検索
tempo_trace	traceID でトレース全体を表示
alerts	現在アラートが発生しているルール
datasources	すべてのデータソースを一覧表示

時間パラメーター（loki/prom/tempo 共通）：range（デフォルトは 1h。例：30m/6h/24h）、start/end（ISO 8601 の絶対時間）、limit。

与官方 mcp-grafana 的差异

Grafana 官方也提供 MCP server（Go 实现，面向全局单实例的完整工具集）。两者定位不同，可并存：

	grafana-mcp（本仓库）	官方 mcp-grafana
使用粒度	项目级：项目根 .grafana.json 声明上下文，project_context 一次对齐	全局实例，项目信息需每次口头提供
多环境	test/prod 双环境一等公民，switch_environment 一键切换	面向单一实例配置
凭据来源	.mcp.json env（零全局依赖）/ ~/.zshrc 文本解析 / 全局配置文件（三选一，可混用）	环境变量
形态	零依赖单文件 TypeScript，bun 直接运行	Go 二进制 / Docker

选型建议：要全量 Grafana 管理能力用官方；要"每个业务项目开箱即用的日志/指标排查上下文 + 双环境"，用本仓库。

安全提示

• Grafana 账号建议使用 Viewer 角色的专用账号，不要复用管理员凭据。
• 凭据明文存于 ~/.zshrc（或进程环境），MCP server 仅在本机内存中使用，不落盘、不回显（project_context 输出对密码脱敏）。
• 如需集中管理，可把连接信息放到 ~/.config/grafana-mcp/config.json 并 chmod 600，~/.zshrc 中的同名变量会被其覆盖。
• 支持 1Password 回退（可选）：设置 GRAFANA_OP_VAULT / GRAFANA_OP_ITEM 后，无账密时通过 op CLI 取凭据。

FAQ

为什么 agent 读不到 .zshrc 里的环境变量？ MCP server 由客户端 spawn，是非交互、非登录 shell，不会 source rc 文件。本实现提供三种解法：① 在 .mcp.json env 中直接配 GRAFANA_{ENV}_*（推荐）② server 解析 rc 文件文本 ③ 用全局配置文件。

不想装 bun？ 当前运行时依赖 bun（单文件 TS 直跑是刻意的设计取舍）。Node 兼容的编译产物在 Roadmap 中，欢迎 issue 催更。

查询结果太长被截断？ 超过 6 万字符自动截断并提示缩小范围；命中 limit 上限时也会明确提示可能还有更多。建议总是带 range 与 limit。

数据源选错了？ 在 GRAFANA_{ENV}_LOKI_DATASOURCE 等变量或 .grafana.json 的 environments.{env}.datasources 中显式指定 UID。

本地开发

bun run smoke    # MCP 协议握手 + 工具清单 + project_context；本机配好凭据后自动追加真实查询
bun run test     # 冒烟 + 集成测试（项目上下文发现、app 注入、prod 切换；需要真实凭据，CI 跳过）

CI 只运行无凭据的协议级冒烟测试与敏感信息扫描；集成测试需要真实 Grafana 环境，请在本机运行。

Roadmap

• Node 兼容编译产物（降低 bun 前提）
• 仪表盘面板数据读取
• 更多环境变量发现来源（direnv 等）

关于作者

itzhouq — 个人网站 itzhouq.cn，在那里持续 build in public。其他开源工具：

• archery-mcp — 让 AI 只读接入 Archery SQL 审计平台的 MCP server（生产表结构查询 + 上线 SQL 预检）

欢迎 issue / PR；安全漏洞请走 SECURITY.md 的私密渠道，不要开 public issue。

---

mcp-name: io.github.itzhouq/grafana-mcp