Loki MCP Server

Loki MCP サーバー

Grafana Loki と連携する、Model Context Protocol（MCP）の Go ベースのサーバー実装です。

はじめに

前提条件

• Go 1.16 以上

ビルドと実行

サーバーをビルドして実行します。

# Build the server
go build -o loki-mcp-server ./cmd/server

# Run the server
./loki-mcp-server

または、Go で直接実行します。

go run ./cmd/server

サーバーは、Model Context Protocol（MCP）に従って標準入力／標準出力と SSE を使用して通信します。そのため、Claude Desktop やその他の MCP 対応クライアントでの使用に適しています。

プロジェクト構成

.
├── cmd/
│   ├── server/       # MCP server implementation
│   └── client/       # Client for testing the MCP server
├── internal/
│   ├── handlers/     # Tool handlers
│   └── models/       # Data models
├── pkg/
│   └── utils/        # Utility functions and shared code
└── go.mod            # Go module definition

MCP サーバー

Loki MCP サーバーは Model Context Protocol（MCP）を実装し、次のツールを提供します。

Loki クエリツール

loki_query ツールを使用すると、Grafana Loki のログデータをクエリできます。

• 必須パラメーター：

  • query：LogQL クエリ文字列

• オプションのパラメーター：

  • url：Loki サーバーの URL（デフォルト：LOKI_URL 環境変数の値、または http://localhost:3100）
  • start：クエリの開始時刻（デフォルト：1 時間前）
  • end：クエリの終了時刻（デフォルト：現在）
  • limit：返すエントリーの最大数（デフォルト：100）
  • org：クエリの組織 ID（X-Scope-OrgID ヘッダーとして送信）

環境変数

Loki クエリツールでは、次の環境変数をサポートしています。

• LOKI_URL：リクエストで指定されていない場合に使用するデフォルトの Loki サーバー URL
• LOKI_ORG_ID：リクエストで指定されていない場合に使用するデフォルトの組織 ID
• LOKI_USERNAME：リクエストで指定されていない場合に使用する、基本認証用のデフォルトのユーザー名
• LOKI_PASSWORD：リクエストで指定されていない場合に使用する、基本認証用のデフォルトのパスワード
• LOKI_TOKEN：リクエストで指定されていない場合に使用する、認証用のデフォルトのベアラートークン

セキュリティに関する注意：認証用の環境変数を使用する場合は、機密性の高い認証情報がログや設定ファイルに漏えいしないよう注意してください。可能な場合は、ユーザー名／パスワードよりもトークンベースの認証を検討してください。

MCP サーバーのテスト

付属のクライアントを使用して、MCP サーバーをテストできます。

# Build the client
go build -o loki-mcp-client ./cmd/client

# Loki query examples:
./loki-mcp-client loki_query "{job=\"varlogs\"}"
./loki-mcp-client loki_query "{job=\"varlogs\"}" "-1h" "now" 100

# Using environment variables:
export LOKI_URL="http://localhost:3100"
./loki-mcp-client loki_query "{job=\"varlogs\"}"

# Using environment variables for both URL and org:
export LOKI_URL="http://localhost:3100"
export LOKI_ORG_ID="tenant-123"
./loki-mcp-client loki_query "{job=\"varlogs\"}"

# Using environment variables for authentication:
export LOKI_URL="http://localhost:3100"
export LOKI_USERNAME="admin"
export LOKI_PASSWORD="password"
./loki-mcp-client loki_query "{job=\"varlogs\"}"

# Using environment variables with bearer token:
export LOKI_URL="http://localhost:3100"
export LOKI_TOKEN="your-bearer-token"
./loki-mcp-client loki_query "{job=\"varlogs\"}"

# Using all environment variables together:
export LOKI_URL="http://localhost:3100"
export LOKI_ORG_ID="tenant-123"
export LOKI_USERNAME="admin"
export LOKI_PASSWORD="password"
./loki-mcp-client loki_query "{job=\"varlogs\"}"

# Using org parameter for multi-tenant setups:
./loki-mcp-client loki_query "{job=\"varlogs\"}" "" "" "" "" "" "tenant-123"

Docker のサポート

Docker を使用して MCP サーバーをビルドし、実行できます。

# Build the Docker image
docker build -t loki-mcp-server .

# Run the server
docker run --rm -i loki-mcp-server

または、Docker Compose を使用できます。

# Build and run with Docker Compose
docker-compose up --build

Loki を使用したローカルテスト

このプロジェクトには、Loki のクエリをローカルでテストするための Docker Compose 環境一式が含まれています。

1. Docker Compose 環境を起動します。

   docker-compose up -d
   

   次のコンテナーが起動します。

   • ポート 3100 で動作する Loki サーバー
   • Loki がデータソースとして事前設定された、ポート 3000 で動作する Grafana インスタンス
   • Loki にサンプルログを送信するログ生成コンテナー
   • Loki MCP サーバー

2. 付属のテストスクリプトを使用してログをクエリします。

   # Run with default parameters (queries last 15 minutes of logs)
   ./test-loki-query.sh
   
   # Query for error logs
   ./test-loki-query.sh '{job="varlogs"} |= "ERROR"'
   
   # Specify a custom time range and limit
   ./test-loki-query.sh '{job="varlogs"}' '-1h' 'now' 50
   

3. テスト用のダミーログを挿入します。

   # Insert 10 dummy logs with default settings
   ./insert-loki-logs.sh
   
   # Insert 20 logs with custom job and app name
   ./insert-loki-logs.sh --num 20 --job "custom-job" --app "my-app"
   
   # Insert logs with custom environment and interval
   ./insert-loki-logs.sh --env "production" --interval 0.5
   
   # Show help message
   ./insert-loki-logs.sh --help
   

4. http://localhost:3000 で Grafana の UI にアクセスし、ログを視覚的に確認します。

Server-Sent Events（SSE）のサポート

サーバーでは、次の 2 つの通信モードをサポートするようになりました。

1. Model Context Protocol（MCP）に従った標準入出力（stdin/stdout）
2. n8n などのツールとの連携に使用する、Server-Sent Events（SSE）エンドポイントを備えた HTTP サーバー

HTTP サーバーのデフォルトポートは 8080 ですが、SSE_PORT 環境変数を使用して設定できます。

サーバーのエンドポイント

HTTP モードで実行すると、サーバーは次のエンドポイントを公開します。

• SSE エンドポイント：http://localhost:8080/sse - リアルタイムのイベントストリーミング用
• MCP エンドポイント：http://localhost:8080/mcp - MCP プロトコルのメッセージング用

SSE を使用した Docker の実行

Docker でサーバーを実行する場合は、ポート 8080 を公開してください。

# Build the Docker image
docker build -t loki-mcp-server .

# Run the server with port mapping
docker run -p 8080:8080 --rm -i loki-mcp-server

n8n との統合

Loki MCP サーバーを n8n のワークフローに統合できます。

1. n8n に MCP Client Tools ノードをインストールします

2. 次のパラメーターを使用してノードを設定します。

   • SSE Endpoint：http://your-server-address:8080/sse（実際のサーバーアドレスに置き換えてください）
   • Authentication：必要に応じて適切な認証を選択します
   • Tools to Include：AI エージェントに公開する Loki ツールを選択します

3. MCP Client Tool ノードを、Loki のクエリ機能を使用する AI Agent ノードに接続します

ワークフローの例： トリガー → MCP Client Tool（Loki サーバー）→ AI Agent（Claude）

アーキテクチャ

Loki MCP サーバーはモジュール型アーキテクチャを採用しています。

• サーバー：cmd/server/main.go にある MCP サーバーの主要な実装
• クライアント：MCP サーバーとやり取りするためのテストクライアント。cmd/client/main.go にあります
• ハンドラー：internal/handlers/ にある個々のツールハンドラー
  • loki.go：Grafana Loki のクエリ機能

Claude Desktop での使用

この MCP サーバーを Claude Desktop で使用すると、Loki のクエリツールを追加できます。次の手順に従ってください。

オプション 1：コンパイル済みバイナリを使用する

1. サーバーをビルドします。

go build -o loki-mcp-server ./cmd/server

2. claude_desktop_config_binary.json を使用して、設定を Claude Desktop の設定ファイルに追加します。

オプション 2：シェルスクリプトで Go Run を使用する

1. スクリプトを実行可能にします。

chmod +x run-mcp-server.sh

2. claude_desktop_config_script.json を使用して、設定を Claude Desktop の設定ファイルに追加します。

オプション 3：Docker を使用する（推奨）

1. Docker イメージをビルドします。

docker build -t loki-mcp-server .

2. claude_desktop_config_docker.json を使用して、設定を Claude Desktop の設定ファイルに追加します。

設定の詳細

Claude Desktop の設定ファイルは次の場所にあります。

• macOS の場合：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows の場合：%APPDATA%\Claude\claude_desktop_config.json
• Linux の場合：~/.config/Claude/claude_desktop_config.json

このリポジトリにあるサンプル設定を使用できます。

• claude_desktop_config.json：汎用テンプレート
• claude_desktop_config_example.json：現在のパスで go run を使用する例
• claude_desktop_config_binary.json：コンパイル済みバイナリを使用する例
• claude_desktop_config_script.json：シェルスクリプトを使用する例（go run での使用を推奨）
• claude_desktop_config_docker.json：Docker を使用する例（最も信頼性が高い方法）

注意：

• Claude Desktop で go run を使用する場合は、スクリプトと設定ファイルの両方で複数の環境変数を設定する必要がある場合があります。

  • HOME：ユーザーのホームディレクトリ
  • GOPATH：Go ワークスペースディレクトリ
  • GOMODCACHE：Go モジュールキャッシュディレクトリ
  • GOCACHE：Go ビルドキャッシュディレクトリ

  これらは、Claude Desktop から実行したときに Go がモジュールとビルドキャッシュを見つけられるようにするために必要です。

• Docker はすべての依存関係と環境変数をコンテナーにまとめるため、最も信頼性の高い方法です。

または、独自の設定を作成します。

{
  "mcpServers": {
    "lokiserver": {
      "command": "path/to/loki-mcp-server",
      "args": [],
      "env": {
        "LOKI_URL": "http://localhost:3100",
        "LOKI_ORG_ID": "your-default-org-id",
        "LOKI_USERNAME": "your-username",
        "LOKI_PASSWORD": "your-password",
        "LOKI_TOKEN": "your-bearer-token"
      },
      "disabled": false,
      "autoApprove": ["loki_query"]
    }
  }
}

path/to/loki-mcp-server は、ビルド済みバイナリまたはソースコードへの絶対パスに置き換えてください。

4. Claude Desktop を再起動します。

5. Claude でツールを使用できるようになります。

   • Loki クエリの例：
     • 「クエリ {job="varlogs"} で Loki のログを検索して」
     • 「クエリ {job="varlogs"} |= "ERROR" を使って、過去 1 時間の Loki のエラーログを見つけて」
     • 「job=varlogs の Loki の最新 50 件のログを表示して」
     • 「クエリ {job="varlogs"} を使って、org 'tenant-123' の Loki のログを検索して」

自然言語のプロンプトで組織 ID を使用する

この MCP サーバーを Claude Desktop または他の AI アシスタントで使用する場合、ユーザーはプロンプト内で組織 ID を自然に指定できます。指定方法はいくつかあります。

組織を直接指定する

• 「クエリ {job="varlogs"} で組織 'tenant-123' の Loki のログを検索して」
• 「{job="web"} を使って、org 'production-env' の Loki ログを検索して」
• 「{service="api"} に一致する、組織 ID 'client-abc' のログを取得して」

コンテキストに応じた組織への言及

• 「クエリ {level="error"} を使って、本番テナント（org: prod-001）のエラーログを確認してください」
• 「過去 1 時間における、顧客組織 'customer-xyz' のすべてのログを検索してください」
• 「org tenant-456 を指定して Loki にクエリを実行し、{job="backend"} に一致するログを検索してください」

マルチテナントのシナリオ

• 「組織 'dev-team' に切り替えて、デバッグ用に {job="logs"} をクエリしてください」
• 「org 'staging-env' を使って、過去 2 時間の警告ログを検索してください」
• 「テナント 'qa-environment' のログから、エラーメッセージを検索してください」

その他のパラメーターとの組み合わせ

• 「2 時間前から現在まで、組織 'prod-cluster' の Loki にクエリを実行し、上限を 50 にしてください」
• 「クエリ {app="payment"} に対する、org 'microservice-team' の直近 100 件のログを取得してください」

これらの自然言語のプロンプトを使うと、AI アシスタントは「organization」、「org」、「tenant」、「organization ID」などの用語を Loki クエリツールの org パラメーターに自動的に対応付けます。このパラメーターは X-Scope-OrgID ヘッダーとして Loki サーバーに送信され、適切なマルチテナントフィルタリングが行われます。

重要なのは、リクエストに特定のパラメーターを自然に含めることです。AI は、それらを適切な Loki クエリツールのパラメーターに対応付ける方法を理解します。パラメーターが明示されていない場合、システムは環境変数のデフォルト値を自動的に使用します。

• Loki サーバーの URL には LOKI_URL
• 組織 ID には LOKI_ORG_ID
• 基本認証には LOKI_USERNAME と LOKI_PASSWORD
• ベアラートークン認証には LOKI_TOKEN

これにより、接続パラメーターを一度設定しておけば、認証情報を毎回指定することなく、自然言語でクエリを実行できます。

Cursor での使用

Loki MCP サーバーは Cursor エディターと統合することもできます。統合するには、次の設定を Cursor の設定に追加してください。

Docker の設定：

{
  "mcpServers": {
    "loki-mcp-server": {
      "command": "docker",
      "args": ["run", "--rm", "-i", 
               "-e", "LOKI_URL=http://host.docker.internal:3100", 
               "-e", "LOKI_ORG_ID=your-default-org-id",
               "-e", "LOKI_USERNAME=your-username",
               "-e", "LOKI_PASSWORD=your-password",
               "-e", "LOKI_TOKEN=your-bearer-token",
               "loki-mcp-server:latest"]
    }
  }
}

この設定を追加した後に Cursor を再起動すると、エディター内で Loki クエリツールを直接使用できるようになります。

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細については LICENSE ファイルを参照してください。

テストの実行

このプロジェクトには、信頼性を確保するための包括的なユニットテストと CI/CD ワークフローが含まれています。

# Run all tests
go test ./...

# Run tests with coverage
go test -coverprofile=coverage.out ./...
go tool cover -func=coverage.out

# Run tests with race detection  
go test -race ./...