grafana-log-mcp

grafana-log-mcp は、Grafana/Loki 向けの汎用的で再利用可能なログ問い合わせレイヤーであり、読み取り専用の stdio MCP サーバーとして公開されています。Grafana の API と通信し、生ログに加えて集約ビュー（スロークエリ、エラーフィンガープリント、ボリュームトレンド）を、時間ウィンドウ、プロジェクト、キーワード、または期間しきい値でフィルタリングして返します。

意図的にビジネス固有のロジックやヒューリスティックは含まれていません。ログを取得した後、ソースコードとの関連付けやなぜ何が起こったのかの説明は、デバッグ対象のビジネスプロジェクトの AI IDE とスキル/ルールに委ねられています。サーバーは単にデータを利用可能にするだけです。

中国語での位置づけ：これは汎用のログ問い合わせレイヤーです（データ取得、集約、ログ返却のみを行い、ビジネス横断で再利用可能）。ビジネス分析や根本原因の帰属は組み込まれておらず、具体的な原因分析は呼び出し側の AI がビジネスプロジェクトのソースコードとプロジェクト自身のスキル/経験を組み合わせて行います。

インストール

# 方式一：npm 全局安装（推荐）
npm install -g grafana-log-mcp

グローバルインストール後、2 つのコマンドが提供されます：grafana-log-mcp（MCP サーバー起動）、grafana-log-mcp-login（対話型ログイン）。

インストールせずに npx で一度だけ実行することもできます：npx -y grafana-log-mcp / npx -y grafana-log-mcp-login。

Related MCP server: grafana-mcp

クイックスタート

npm インストール済み（利用側）

# 1. 登录（交互输入 Grafana 地址与用户名密码，写入 ~/.grafana-log-mcp/credentials.json，0600）
grafana-log-mcp-login

# 2. 校验凭证（排查"MCP 突然查不了"）
grafana-log-mcp-login --check

# 3. 启动 MCP Server（stdio）
grafana-log-mcp

ソースコード開発（リポジトリを clone した後）

# 1. 安装依赖（node >= 18）
npm install

# 2. 登录
node bin/login.js

# 3. 校验凭证
node bin/login.js --check

# 4. 启动 MCP Server（stdio）
npm start          # 即 node src/index.js

AI IDE への接続（Trae/Claude など）

MCP 設定に追加します（各 IDE の設定形式に従います）：

{
  "mcpServers": {
    "grafana-log": {
      "command": "npx",
      "args": ["-y", "grafana-log-mcp"],
      "env": { "GRAFANA_URL": "https://your-grafana.example.com" }
    }
  }
}

グローバル有効化を推奨：トラブルシューティング時にはビジネスプロジェクトのソースコードリポジトリを開くため、MCP 設定をグローバルに追加すれば、任意のリポジトリで直接「質問 → ログ確認 → コード閲覧 → 原因提示」が可能です。

ツール（15 個）

データ量の 3 つのハード上限：limit ≤ 1000、単行 500 文字、レスポンス 25k 文字（超過時は先頭と末尾を保持し中段を省略して注記）。単行が切り捨てられた場合は get_full_line でその行の time を指定して完全な内容を取得できます。

プロジェクト登録（projects.json）

登録ファイルは以下の優先順位で特定されます（list_projects が返す summary.configFile に現在実際に有効な場所が表示されます）：

1. GRAFANA_CONFIG_PATH 環境変数で指定されたファイル

2. パッケージ内の config/projects.json（ソースコードリポジトリ内）

3. ~/.grafana-log-mcp/projects.json（認証情報と同じディレクトリ、npm インストール後のデフォルト位置）

参考形式は config/projects.example.json にあり、各項目には key / datasourceUid / labels{app,group} / aliases(中国語エイリアス) / repoPath が含まれます。repoPath は AI IDE がコードを特定するためだけに使用され、MCP 自体はソースコードを読みません。障害ナレッジベースは config/failure-patterns.json にあり、新しい障害タイプに遭遇したらエントリを追加するだけです。

環境変数（オプション）

GRAFANA_URL=                  # Grafana 地址：作为 grafana-log-mcp-login 的默认地址，并覆盖凭证文件中的地址
GRAFANA_ORG_ID=1              # 可选：仅影响 build_explore_url 生成的 Explore 深链的 orgId 参数（默认 1）；不参与实际日志查询
GRAFANA_CREDENTIALS_PATH=     # 自定义凭证文件位置
GRAFANA_CONFIG_PATH=          # 自定义项目登记文件（projects.json）位置
GRAFANA_MOCK=1                # 本地 mock 模式：不连真实 Grafana、无需登录（2500 条合成日志，验证翻页/截断/慢日志）

説明：MCP には Grafana のデフォルトアドレスやプロジェクト設定は組み込まれていません（汎用化）。アドレスはログイン時に入力したもの（認証情報ファイル）または GRAFANA_URL 環境変数から取得します。インスタンス関連の設定（プロジェクト登録、データソース uid）は projects.json で管理されます（前節の特定ルールを参照）。

テスト

node test/unit.mjs         # 纯逻辑单测（合成日志，无网络依赖）：59 通过
node test/integration.mjs  # 编排器端到端（mock client + 独立 fixture 配置）：20 通过