mcp-victoriatraces

VictoriaTraces MCP サーバー

VictoriaTraces 用の Model Context Protocol (MCP) サーバーの実装です。

VictoriaTraces インスタンスへのアクセスを提供し、VictoriaTraces API およびドキュメントとシームレスに連携できます。 VictoriaTraces インスタンスに関連するトレース、可観測性、デバッグ作業の包括的なインターフェースを提供し、エンジニアやツール向けの高度な自動化機能と対話機能を実現します。

機能

この MCP サーバーでは、VictoriaTraces のほぼすべての読み取り専用 API を利用できます。

• サービスとオペレーション（スパン名）を取得する
• トレースをクエリし、トレースデータを調査・分析する

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

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

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

MCP サーバーを他の可観測性またはドキュメント検索用の MCP サーバーと組み合わせれば、さらに強力な結果を得られます。

要件

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

インストール

Go

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

バイナリ

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

Linux x86_64 の例（他のアーキテクチャやプラットフォームにも対応しています）。

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

Docker

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

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

docker run -d --name mcp-victoriatraces \
  -e VT_INSTANCE_ENTRYPOINT=https://localhost:10428 \
  -e MCP_SERVER_MODE=http \
  -e MCP_LISTEN_ADDR=:8081 \
  -p 8081:8081 \
  ghcr.io/victoriametrics-community/mcp-victoriatraces

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

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

利用可能な Docker イメージについては、github registry をご覧ください。

MCP サーバーを stdio モードのクライアントとともに Docker で使用する方法の詳細については、Using Docker instead of binary セクションもご覧ください。

Source Code

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

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

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

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

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

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

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

Helm

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

Configuration

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

Variable	Description	Required	Default	Allowed values
VT_INSTANCE_ENTRYPOINT	VictoriaTraces インスタンスの URL	はい	-	-
VT_INSTANCE_BEARER_TOKEN	VictoriaTraces API の認証トークン	いいえ	-	-
VT_INSTANCE_HEADERS	リクエストとともに送信するカスタム HTTP ヘッダー（キーと値のペアをカンマ区切りで指定）	いいえ	-	-
VT_DEFAULT_TENANT_ID	リクエストでテナントが指定されていない場合に使用するデフォルトのテナント ID（形式：AccountID:ProjectID または AccountID）	いいえ	0:0	-
MCP_SERVER_MODE	サーバーの動作モードです。詳細は Modes をご覧ください。	いいえ	stdio	stdio、sse、http
MCP_LISTEN_ADDR	SSE または HTTP サーバーが待ち受けるアドレス	いいえ	localhost:8081	-
MCP_DISABLED_TOOLS	無効にするツールのカンマ区切りリスト	いいえ	-	-
MCP_HEARTBEAT_INTERVAL	streamable-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 - ストリーミング可能な HTTP です。サーバーは、HTTP 接続用に /mcp エンドポイントを公開します。

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

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

設定例

export VT_INSTANCE_ENTRYPOINT="https://localhost:10428"

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

# Server mode
export MCP_SERVER_MODE="sse"
export MCP_SSE_ADDR="0.0.0.0:8082"

エンドポイント

SSE モードと HTTP モードでは、MCP サーバーは次のエンドポイントを提供します。

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

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

Cursor

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

{
  "mcpServers": {
    "victoriatraces": {
      "command": "/path/to/mcp-victoriatraces",
      "env": {
        "VT_INSTANCE_ENTRYPOINT": "<YOUR_VT_INSTANCE>",
        "VT_INSTANCE_BEARER_TOKEN": "<YOUR_VT_BEARER_TOKEN>",
        "VT_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
      }
    }
  }
}

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

Claude Desktop

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

{
  "mcpServers": {
    "victoriatraces": {
      "command": "/path/to/mcp-victoriatraces",
      "env": {
        "VT_INSTANCE_ENTRYPOINT": "<YOUR_VT_INSTANCE>",
        "VT_INSTANCE_BEARER_TOKEN": "<YOUR_VT_BEARER_TOKEN>",
        "VT_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
      }
    }
  }
}

詳細については、Claude Desktop MCP のドキュメントをご覧ください。

Claude Code

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

claude mcp add victoriatraces -- /path/to/mcp-victoriatraces \
  -e VT_INSTANCE_ENTRYPOINT=<YOUR_VT_INSTANCE> \
  -e VT_INSTANCE_BEARER_TOKEN=<YOUR_VT_BEARER_TOKEN> \
  -e VT_INSTANCE_HEADERS="<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"

詳細については、Claude Code MCP のドキュメントをご覧ください。

Visual Studio Code

次の内容を VS Code の MCP 設定ファイルに追加します。

{
  "servers": {
    "victoriatraces": {
      "type": "stdio",
      "command": "/path/to/mcp-victoriatraces",
      "env": {
        "VT_INSTANCE_ENTRYPOINT": "<YOUR_VT_INSTANCE>",
        "VT_INSTANCE_BEARER_TOKEN": "<YOUR_VT_BEARER_TOKEN>",
        "VT_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
      }
    }
  }
}

詳細については、VS Code MCP のドキュメントをご覧ください。

Zed

次の内容を Zed の設定ファイルに追加します。

  "context_servers": {
    "victoriatraces": {
      "command": {
        "path": "/path/to/mcp-victoriatraces",
        "args": [],
        "env": {
          "VT_INSTANCE_ENTRYPOINT": "<YOUR_VT_INSTANCE>",
          "VT_INSTANCE_BEARER_TOKEN": "<YOUR_VT_BEARER_TOKEN>",
          "VT_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
        }
      },
      "settings": {}
    }
  }
}

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

JetBrains IDEs

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

{
  "mcpServers": {
    "victoriatraces": {
      "command": "/path/to/mcp-victoriatraces",
      "env": {
        "VT_INSTANCE_ENTRYPOINT": "<YOUR_VT_INSTANCE>",
        "VT_INSTANCE_BEARER_TOKEN": "<YOUR_VT_BEARER_TOKEN>",
        "VT_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
      }
    }
  }
}

Windsurf

次の内容を Windsurf の MCP 設定ファイルに追加します。

{
  "mcpServers": {
    "victoriatraces": {
      "command": "/path/to/mcp-victoriatraces",
      "env": {
        "VT_INSTANCE_ENTRYPOINT": "<YOUR_VT_INSTANCE>",
        "VT_INSTANCE_BEARER_TOKEN": "<YOUR_VT_BEARER_TOKEN>",
        "VT_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
      }
    }
  }
}

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

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

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

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

{
  "mcpServers": {
    "victoriatraces": {
      "command": "docker",
        "args": [
          "run",
          "-i", "--rm",
          "-e", "VT_INSTANCE_ENTRYPOINT",
          "-e", "VT_INSTANCE_BEARER_TOKEN",
          "-e", "VT_INSTANCE_HEADERS",
          "ghcr.io/victoriametrics-community/mcp-victoriatraces",
        ],
      "env": {
        "VT_INSTANCE_ENTRYPOINT": "<YOUR_VT_INSTANCE>",
        "VT_INSTANCE_BEARER_TOKEN": "<YOUR_VT_BEARER_TOKEN>",
        "VT_INSTANCE_HEADERS": "<HEADER>=<HEADER_VALUE>,<HEADER>=<HEADER_VALUE>"
      }
    }
  }
}

使用方法

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

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

Use MCP VictoriaTraces in the following answers

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

ツールセット

MCP VictoriaTraces は、お使いの VictoriaTraces インスタンスと連携するためのさまざまなツールを提供します。

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

ツール	説明
documentation	埋め込みの VictoriaTraces ドキュメントを検索する
services	トレース対象のすべてのサービスを一覧表示する
service_names	サービスのすべてのスパン名（操作）を取得する
traces	トレースをクエリする
trace	トレース ID でトレース情報を取得する
dependencies	サービス依存関係グラフをクエリする

プロンプト

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

現時点ではこれらはサンプルにすぎません。今後、プロンプトライブラリを拡充する予定です。

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

ロードマップ

• MCP のマルチテナント版を実装する（複数のデプロイメントに対応）
• この機能のリリース後にサービスグラフツールを追加する（PRを参照）

免責事項

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

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

コントリビューション

MCP VictoriaTraces プロジェクトへのコントリビューションを歓迎します！

お気軽にイシューや機能リクエストを送信したり、プルリクエストを作成したりしてください。