mcp-victorialogs

VictoriaLogs MCP サーバー

VictoriaLogs 向けの Model Context Protocol（MCP） サーバーの実装です。

VictoriaLogs インスタンスへのアクセスと、VictoriaLogs API およびドキュメントとのシームレスな統合を実現します。 VictoriaLogs インスタンスに関連するログ、オブザーバビリティ、デバッグタスクに対応する包括的なインターフェースを提供し、エンジニアやツール向けの高度な自動化機能と操作機能を実現します。

機能

この MCP サーバーでは、VictoriaLogs のほぼすべての読み取り専用 API、つまりWeb UIで利用可能なすべての機能を使用できます。

• ログのクエリとログデータの調査
• VictoriaLogs インスタンスのパラメーターの表示
• 利用可能なストリーム、フィールド、フィールド値の一覧表示
• ログの統計情報をメトリクスとしてクエリ
• ルートエンドポイントでの、セットアップ手順とツールの確認に対応した UI（Streamable HTTP モードのみ）

さらに、この MCP サーバーには最新のドキュメントが組み込まれており、オンラインアクセスなしで検索できます。

利用可能なツールとプロンプトの詳細については、使用方法のセクションをご覧ください。

ツールの機能とプロンプト内でのドキュメント検索を組み合わせれば、VictoriaLogs インスタンスで活用できる優れた利用シナリオを考案できます。 また、MCP サーバーの品質と応答は、クライアントの機能と使用するモデルの品質に大きく依存する点にご注意ください。

この MCP サーバーを、オブザーバビリティやドキュメント検索に関連する他の MCP サーバーと組み合わせることで、さらに強力な結果を得ることもできます。

インストールせずに試す

インストールせずに機能を試せる、一般公開されている VictoriaMetrics MCP サーバーのインスタンスがあります。

https://play-vmlogs-mcp.victoriametrics.com/mcp

ご注意ください！ この URL はブラウザーで開くことを想定しておらず、MCP クライアントでの使用を目的としています。

Public VictoriaLogs Playground で動作するように設定されており、Streamable HTTP モードで利用できます。

Claude Desktop の設定例を次に示します。

要件

• VictoriaLogs インスタンス（シングルノードまたはクラスター）
• Go 1.26 以降（ソースからビルドする場合）

インストール

Go

go install github.com/VictoriaMetrics/mcp-victorialogs/cmd/mcp-victorialogs@latest

バイナリ

Releases ページから最新リリースをダウンロードし、PATH に配置してください。

Linux x86_64 の例です（他のアーキテクチャやプラットフォーム向けのものも利用できます）。

latest=$(curl -s https://api.github.com/repos/VictoriaMetrics/mcp-victorialogs/releases/latest | grep 'tag_name' | cut -d\" -f4)
wget https://github.com/VictoriaMetrics/mcp-victorialogs/releases/download/$latest/mcp-victorialogs_Linux_x86_64.tar.gz
tar axvf mcp-victorialogs_Linux_x86_64.tar.gz

Docker

Docker を使用して VictoriaLogs MCP Server を実行できます。

Go のインストールやソースからのビルドが不要なため、最も簡単に始められる方法です。

docker run -d --name mcp-victorialogs \
  -e VL_INSTANCE_ENTRYPOINT=https://play-vmlogs.victoriametrics.com \
  -e MCP_SERVER_MODE=http \
  -e MCP_LISTEN_ADDR=:8081 \
  -p 8081:8081 \
  ghcr.io/victoriametrics/mcp-victorialogs

環境変数は、ご自身のパラメーターに置き換えてください。

MCP_SERVER_MODE=http フラグは、Streamable HTTP モードを有効にするために使用されます。 サーバーモードの詳細については、設定セクションをご覧ください。

利用可能な Docker イメージについては、GitHub レジストリをご覧ください。

また、stdio モードのクライアントで MCP サーバーと Docker を使用する方法の詳細については、バイナリの代わりに Docker を使用するセクションをご覧ください。

Source Code

ソースコードからバイナリをビルドするには、次の手順を使用できます。

• リポジトリをクローンします。

  git clone https://github.com/VictoriaMetrics/mcp-victorialogs.git
  cd mcp-victorialogs
  

• クローンしたソースコードからバイナリをビルドします。

  make build
  # after that you can find binary mcp-victorialogs and copy this file to your PATH or run inplace
  

• クローンしたソースコードからイメージをビルドします。

  docker build -t mcp-victorialogs .
  # after that you can use docker image mcp-victorialogs for running or pushing
  

Helm

Helm を使用したインストールの詳細については、VictoriaLogs MCP Server Helm チャートのドキュメントをご覧ください。

Configuration

VictoriaLogs の MCP サーバーは、環境変数で設定します。

変数	説明	必須	デフォルト	許可される値
VL_INSTANCE_ENTRYPOINT	VictoriaLogs インスタンスの URL	はい	-	-
VL_INSTANCE_BEARER_TOKEN	VictoriaLogs API の認証トークン	いいえ	-	-
VL_INSTANCE_HEADERS	リクエストとともに送信するカスタム HTTP ヘッダー（カンマ区切りの key=value ペア）	いいえ	-	-
MCP_PASSTHROUGH_HEADERS	受信した MCP リクエストから VictoriaLogs に転送する HTTP ヘッダー名（カンマ区切りのリスト）。競合する場合は VL_INSTANCE_HEADERS を上書きします。sse／http モードでのみ適用されます。	いいえ	-	-
VL_DEFAULT_TENANT_ID	リクエストでテナントが指定されていない場合に使用するデフォルトのテナント ID（形式：AccountID:ProjectID または AccountID）	いいえ	0:0	-
MCP_SERVER_MODE	サーバーの動作モード。詳細はモードを参照してください。	いいえ	stdio	stdio、sse、http
MCP_LISTEN_ADDR	SSE または HTTP サーバーがリッスンするアドレス	いいえ	localhost:8081	-
MCP_DISABLED_TOOLS	無効にするツールのカンマ区切りリスト	いいえ	-	-
MCP_HEARTBEAT_INTERVAL	ストリーマブル HTTP プロトコルのハートビート間隔を定義します。 MCP サーバーが GET 接続を通じてクライアントにハートビートを送信し、 ゲートウェイなどのネットワークインフラによって接続が切断されないようにします。	いいえ	30s	-
MCP_LOG_FORMAT	ログ出力形式	いいえ	text	text、json
MCP_LOG_LEVEL	最小ログレベル	いいえ	info	debug、info、warn、error

モード

MCP サーバーは、以下の動作モード（トランスポート）に対応しています。

• stdio - 標準入出力モードです。サーバーは標準入力からコマンドを読み取り、標準出力に応答を書き込みます。これがデフォルトのモードで、ローカルサーバーに適しています。
• sse - Server-Sent Events です。サーバーは、SSE 接続用に /sse および /message エンドポイントを公開します。
• http - Streamable HTTP です。サーバーは、HTTP 接続用に /mcp エンドポイントを公開します。

トランスポートの詳細については、MCP のドキュメントをご覧ください。

• 基本概念 -> トランスポート
• 仕様 -> トランスポート

設定例

# For a public playground
export VL_INSTANCE_ENTRYPOINT="https://play-vmlogs.victoriametrics.com"

# Custom headers for authentication (e.g., behind a reverse proxy)
# Expected syntax is key=value separated by commas
export VL_INSTANCE_HEADERS="<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"

# Forward specific headers from incoming MCP requests to VictoriaLogs
export MCP_PASSTHROUGH_HEADERS="X-Token,X-Access-Key"

# Server mode
export MCP_SERVER_MODE="sse"
export MCP_SSE_ADDR="0.0.0.0:8081"
export MCP_DISABLED_TOOLS="hits,facets"

エンドポイント

SSE モードおよび HTTP モードでは、MCP サーバーは以下のエンドポイントを提供します。

エンドポイント	説明
/	セットアップのヘルプとツールの確認ができるランディングページ（HTTP モードのみ）
/sse + /message	SSE モードのメッセージ用エンドポイント（SSE に対応した MCP クライアント向け）
/mcp	HTTP モードでメッセージをストリーミングするための HTTP エンドポイント（Streamable HTTP に対応した MCP クライアント向け）
/metrics	MCP サーバーの監視用 Prometheus 形式のメトリクス
/health/liveness	サーバーが実行中であることを確認するための稼働状況チェックエンドポイント
/health/readiness	サーバーがリクエストを受け付ける準備ができていることを確認するための準備状況チェックエンドポイント

クライアントでのセットアップ

Cursor

Settings -> Cursor Settings -> MCP -> Add new global MCP server を開き、以下の設定を Cursor の ~/.cursor/mcp.json ファイルに貼り付けます。

{
  "mcpServers": {
    "victorialogs": {
      "command": "/path/to/mcp-victorialogs",
      "env": {
        "VL_INSTANCE_ENTRYPOINT": "<YOUR_VL_INSTANCE>",
        "VL_INSTANCE_BEARER_TOKEN": "<YOUR_VL_BEARER_TOKEN>",
        "VL_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
      }
    }
  }
}

詳しくは Cursor MCP のドキュメントをご覧ください。

Claude Desktop

以下を Claude Desktop の claude_desktop_config.json ファイルに追加します（Settings -> Developer -> Edit config を開くと見つかります）。

{
  "mcpServers": {
    "victorialogs": {
      "command": "/path/to/mcp-victorialogs",
      "env": {
        "VL_INSTANCE_ENTRYPOINT": "<YOUR_VL_INSTANCE>",
        "VL_INSTANCE_BEARER_TOKEN": "<YOUR_VL_BEARER_TOKEN>",
        "VL_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
      }
    }
  }
}

詳しくは Claude Desktop MCP のドキュメントをご覧ください。

Claude Code

以下のコマンドを実行します。

claude mcp add victorialogs -- /path/to/mcp-victorialogs \
  -e VL_INSTANCE_ENTRYPOINT=<YOUR_VL_INSTANCE> \
  -e VL_INSTANCE_BEARER_TOKEN=<YOUR_VL_BEARER_TOKEN> \
  -e VL_INSTANCE_HEADERS="<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"

詳しくは Claude Code MCP のドキュメントをご覧ください。

Codex

Codex CLI と IDE 拡張機能は、同じ MCP 設定ファイルを使用します。~/.codex/config.toml（または信頼済みプロジェクト内の .codex/config.toml）です。

以下のコマンドを実行します。

codex mcp add victorialogs \
  --env VL_INSTANCE_ENTRYPOINT=<YOUR_VL_INSTANCE> \
  --env VL_INSTANCE_BEARER_TOKEN=<YOUR_VL_BEARER_TOKEN> \
  --env VL_INSTANCE_HEADERS="<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>" \
  -- /path/to/mcp-victorialogs

または、以下を Codex の ~/.codex/config.toml ファイルに追加します。

[mcp_servers.victorialogs]
command = "/path/to/mcp-victorialogs"

[mcp_servers.victorialogs.env]
VL_INSTANCE_ENTRYPOINT = "<YOUR_VL_INSTANCE>"
VL_INSTANCE_BEARER_TOKEN = "<YOUR_VL_BEARER_TOKEN>"
VL_INSTANCE_HEADERS = "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"

サーバーを Streamable HTTP モードで実行する場合は、次のように登録できます。

codex mcp add victorialogs --url http://localhost:8081/mcp

詳しくは Codex MCP のドキュメントをご覧ください。

Visual Studio Code

以下を VS Code の MCP 設定ファイルに追加します。

{
  "servers": {
    "victorialogs": {
      "type": "stdio",
      "command": "/path/to/mcp-victorialogs",
      "env": {
        "VL_INSTANCE_ENTRYPOINT": "<YOUR_VL_INSTANCE>",
        "VL_INSTANCE_BEARER_TOKEN": "<YOUR_VL_BEARER_TOKEN>",
        "VL_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
      }
    }
  }
}

詳しくは VS Code MCP のドキュメントをご覧ください。

Zed

以下を Zed の設定ファイルに追加します。

  "context_servers": {
    "victorialogs": {
      "command": {
        "path": "/path/to/mcp-victorialogs",
        "args": [],
        "env": {
                  "VL_INSTANCE_ENTRYPOINT": "<YOUR_VL_INSTANCE>",
        "VL_INSTANCE_BEARER_TOKEN": "<YOUR_VL_BEARER_TOKEN>",
        "VL_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
      }
      },
      "settings": {}
    }
  }
}

詳しくは Zed MCP のドキュメントをご覧ください。

JetBrains IDE

• Settings -> Tools -> AI Assistant -> Model Context Protocol (MCP) を開きます。
• Add (+) をクリックします。
• As JSON を選択します。
• 以下を入力欄に貼り付けます。

{
  "mcpServers": {
    "victorialogs": {
      "command": "/path/to/mcp-victorialogs",
      "env": {
        "VL_INSTANCE_ENTRYPOINT": "<YOUR_VL_INSTANCE>",
        "VL_INSTANCE_BEARER_TOKEN": "<YOUR_VL_BEARER_TOKEN>",
        "VL_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
      }
    }
  }
}

Windsurf

以下を Windsurf の MCP 設定ファイルに追加します。

{
  "mcpServers": {
    "victorialogs": {
      "command": "/path/to/mcp-victorialogs",
      "env": {
        "VL_INSTANCE_ENTRYPOINT": "<YOUR_VL_INSTANCE>",
        "VL_INSTANCE_BEARER_TOKEN": "<YOUR_VL_BEARER_TOKEN>",
        "VL_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
      }
    }
  }
}

詳しくは Windsurf MCP のドキュメントをご覧ください。

バイナリの代わりに Docker を使用する

ローカルのバイナリの代わりに Docker を使用して VictoriaLogs MCP Server を実行できます。

上記の設定例にある実行コマンドを、次のように置き換えてください。

{
  "mcpServers": {
    "victorialogs": {
      "command": "docker",
        "args": [
          "run",
          "-i", "--rm",
          "-e", "VL_INSTANCE_ENTRYPOINT",
          "-e", "VL_INSTANCE_BEARER_TOKEN",
          "-e", "VL_INSTANCE_HEADERS",
          "ghcr.io/victoriametrics/mcp-victorialogs",
        ],
      "env": {
        "VL_INSTANCE_ENTRYPOINT": "<YOUR_VL_INSTANCE>",
        "VL_INSTANCE_BEARER_TOKEN": "<YOUR_VL_BEARER_TOKEN>",
        "VL_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
      }
    }
  }
}

使用方法

MCP サーバーをインストールして設定した後、お好みの MCP クライアントで使用を開始できます。

次のフレーズから AI アシスタントとの対話を開始できます。

Use MCP VictoriaLogs in the following answers

ただし、これは必須ではありません。質問するだけで、アシスタントがツールとドキュメントを自動的に使用して、最適な回答を提供します。

ツールセット

MCP VictoriaLogs には、VictoriaLogs インスタンスとやり取りするための多数のツールが用意されています。

利用可能なツールの一覧は次のとおりです。

ツール	説明
documentation	VictoriaLogs の組み込みドキュメントを検索します
facets	各ログフィールドで最も頻出する値を取得します
field_names	クエリのフィールド名一覧を取得します
field_values	クエリのフィールド値一覧を取得します
flags	VictoriaLogs インスタンスのデフォルト以外のフラグを表示します
hits	一致するログエントリー数をバケットごとにグループ化して取得します
query	LogsQL クエリを実行します
stats_query	指定した時刻のログ統計をクエリします
stats_query_range	指定した時間範囲のログ統計をクエリします
stream_field_names	クエリのストリームフィールド一覧を取得します
stream_field_values	クエリのストリームフィールド値一覧を取得します
stream_ids	クエリのストリーム ID 一覧を取得します
streams	クエリのストリーム一覧を取得します

プロンプト

サーバーには、一般的なタスク向けの事前定義済みプロンプトが含まれています。

現時点ではあくまで例であり、今後プロンプトライブラリを拡充する予定です。

プロンプト	説明
documentation	特定のトピックについて VictoriaLogs のドキュメントを検索します

FAQ

MCP サーバーが、単純な API プロキシに期待されるより多くのリソースを使用するのはなぜですか？

サーバーには、documentation ツール用の VictoriaMetrics のドキュメントとブログ記事を含むベクトルデータベースが組み込まれています。 これにより、すべてのデータを LLM に渡さずに、VictoriaLogs に関する複雑な質問に回答できます。
これがリソース使用量の主な原因です。使用量を減らすには、環境変数 MCP_DISABLED_TOOLS に documentation を追加して、ベクトルデータベースの読み込みを完全に無効にします。

1 つの MCP サーバーインスタンスを複数の VictoriaMetrics インスタンスで使用するにはどうすればよいですか？

MCP Server の MCP_PASSTHROUGH_HEADERS パラメーターと、vmauth のヘッダーベースルーティングを組み合わせると、MCP クライアント設定の HTTP ヘッダー値に基づいて、MCP 呼び出しをインスタンス間でルーティングできます。

ロードマップ

• 「クエリの説明」ツールをサポートする
• VictoriaMetrics Cloud とのオプションの統合をサポートする
• 現在のドキュメントツールに加えて、サーバーに追加のナレッジを追加する：
  • VictoriaMetrics ブログの記事
  • GitHub のイシュー
  • 公開 Slack チャットの履歴
  • CRD スキーマ
• MCP のマルチテナント版（複数のデプロイメントに対応）を実装する
• フラグ／設定の検証ツールを追加する
• 設定によるツールの有効化／無効化

免責事項

このような MCP サーバーを含む AI サービスやエージェントは、結果の正確性、完全性、信頼性を保証できません。 AI で得られた結果は必ず再確認してください。

MCP Server の品質と応答は、使用するクライアントの機能やモデルの品質に大きく左右されます。

貢献

MCP VictoriaLogs プロジェクトへの貢献を歓迎します！

問題の報告、機能リクエスト、プルリクエストをお気軽にお寄せください。