Milvus MCP Server

公式

Search, Query and interact with data in your Milvus Vector Database.

GitHub
233

ドキュメント

Milvus 用 MCP サーバー

Model Context Protocol (MCP) は、LLM アプリケーションと外部データソースやツールとのシームレスな統合を可能にするオープンプロトコルです。AI 搭載 IDE の構築、チャットインターフェースの強化、カスタム AI ワークフローの作成など、MCP は LLM が必要なコンテキストに接続するための標準化された方法を提供します。

このリポジトリには、Milvus ベクトルデータベース機能へのアクセスを提供する MCP サーバーが含まれています。

MCP with Milvus

前提条件

この MCP サーバーを使用する前に、以下を確認してください。

  • Python 3.10 以上
  • 稼働中の Milvus インスタンス (ローカルまたはリモート)
  • uv のインストール (サーバー実行に推奨)

使用方法

この MCP サーバーの推奨される使用方法は、インストールせずに uv で直接実行することです。以下の例では、Claude Desktop と Cursor の両方がこの方法で使用するように設定されています。

リポジトリをクローンする場合:

git clone https://github.com/zilliztech/mcp-server-milvus.git
cd mcp-server-milvus

その後、サーバーを直接実行できます。

uv run src/mcp_server_milvus/server.py --milvus-uri http://localhost:19530

または、src/mcp_server_milvus/ ディレクトリ内の .env ファイルを変更して環境変数を設定し、次のコマンドでサーバーを実行することもできます。

uv run src/mcp_server_milvus/server.py

重要: .env ファイルはコマンドライン引数よりも優先されます。

実行モード

サーバーは stdio (デフォルト) と SSE (Server-Sent Events) の 2 つの実行モードをサポートしています。

Stdio モード (デフォルト)

  • 説明: 標準入出力を介してクライアントと通信します。モードが指定されていない場合、これがデフォルトです。

  • 使用方法:

    uv run src/mcp_server_milvus/server.py --milvus-uri http://localhost:19530

SSE モード

  • 説明: 通信に HTTP Server-Sent Events を使用します。このモードでは、複数のクライアントが HTTP 経由で接続でき、Web ベースのアプリケーションに適しています。

  • 使用方法:

    uv run src/mcp_server_milvus/server.py --sse --milvus-uri http://localhost:19530 --port 8000
    • --sse: SSE モードを有効にします。
    • --port: SSE サーバーのポートを指定します (デフォルト: 8000)。

  • SSE モードでのデバッグ:

    SSE モードでデバッグする場合、SSE サービスを開始した後、次のコマンドを入力します。

    mcp dev src/mcp_server_milvus/server.py

    出力は次のようになります。

    % mcp dev src/mcp_server_milvus/merged_server.py
Starting MCP inspector...
⚙️ Proxy server listening on port 6277
🔍 MCP Inspector is up and running at http://127.0.0.1:6274 🚀

    その後、http://127.0.0.1:6274 で MCP Inspector にアクセスしてテストできます。

ストリーミング HTTP モード

  • 説明: ストリーミングをサポートする HTTP を通信に使用します。これは本番環境デプロイメントに推奨されるトランスポートであり、ステートフル操作とステートレス操作の両方をサポートします。

  • 使用方法:

    uv run src/mcp_server_milvus/server.py --streamable-http --milvus-uri http://localhost:19530 --port 8000
    • --streamable-http: ストリーミング HTTP モードを有効にします。
    • --port: サーバーのポートを指定します (デフォルト: 8000)。
    • --stateless: ステートレスモード (セッション永続化なし) のオプションフラグ。

  • ステートレスモード:

    uv run src/mcp_server_milvus/server.py --streamable-http --stateless --milvus-uri http://localhost:19530 --port 8000

サポートされているアプリケーション

この MCP サーバーは、Model Context Protocol をサポートするさまざまな LLM アプリケーションで使用できます。

  • Claude Desktop: Anthropic の Claude 用デスクトップアプリケーション
  • Cursor: MCP サポートを備えた AI 搭載コードエディタ
  • カスタム MCP クライアント: MCP クライアント仕様を実装する任意のアプリケーション

Claude Desktop での使用

異なるモードの設定

SSE モードの設定

Claude Desktop を SSE モード用に設定するには、次の手順に従います。

  1. https://claude.ai/download. から Claude Desktop をインストールします。
  2. Claude Desktop 設定ファイルを開きます。
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  3. SSE モード用に次の設定を追加します。
{
  "mcpServers": {
    "milvus-sse": {
      "url": "http://your_sse_host:port/sse",
      "disabled": false,
      "autoApprove": []
    }
  }
}

ストリーミング HTTP モードの設定

{
  "mcpServers": {
    "milvus-streamable-http": {
      "url": "http://your_host:port/mcp",
      "disabled": false,
      "autoApprove": []
    }
  }
}
  1. Claude Desktop を再起動して変更を適用します。

Stdio モードの設定

stdio モードの場合は、次の手順に従います。

  1. https://claude.ai/download. から Claude Desktop をインストールします。
  2. Claude Desktop 設定ファイルを開きます。
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  3. stdio モード用に次の設定を追加します。
{
  "mcpServers": {
    "milvus": {
      "command": "/PATH/TO/uv",
      "args": [
        "--directory",
        "/path/to/mcp-server-milvus/src/mcp_server_milvus",
        "run",
        "server.py",
        "--milvus-uri",
        "http://localhost:19530"
      ]
    }
  }
}
  1. Claude Desktop を再起動して変更を適用します。

Cursor での使用

Cursor も MCP ツールをサポートしています。次の手順で Milvus MCP サーバーを Cursor と統合できます。

統合手順

  1. Cursor Settings > MCP を開きます。
  2. Add new global MCP server をクリックします。
  3. クリックすると、自動的に mcp.json ファイルにリダイレクトされます。ファイルが存在しない場合は作成されます。

mcp.json ファイルの設定

Stdio モードの場合:

mcp.json ファイルを次の内容で上書きします。

{
  "mcpServers": {
    "milvus": {
      "command": "/PATH/TO/uv",
      "args": [
        "--directory",
        "/path/to/mcp-server-milvus/src/mcp_server_milvus",
        "run",
        "server.py",
        "--milvus-uri",
        "http://127.0.0.1:19530"
      ]
    }
  }
}

SSE モードの場合:

  1. 次のコマンドを実行してサービスを開始します。

    uv run src/mcp_server_milvus/server.py --sse --milvus-uri http://your_sse_host --port port

    注意: http://your_sse_host を実際の SSE ホストアドレスに、port を使用している特定のポート番号に置き換えてください。

  2. サービスが起動したら、mcp.json ファイルを次の内容で上書きします。

    {
    "mcpServers": {
      "milvus-sse": {
        "url": "http://your_sse_host:port/sse",
        "disabled": false,
        "autoApprove": []
      }
    }
}

ストリーミング HTTP モードの場合:

  1. サービスを開始します。

    uv run src/mcp_server_milvus/server.py --streamable-http --milvus-uri http://your_host --port port

  2. mcp.json を更新します。

    {
  "mcpServers": {
    "milvus-streamable-http": {
      "url": "http://your_host:port/mcp",
      "disabled": false,
      "autoApprove": []
    }
  }
}

統合の完了

上記の手順を完了したら、Cursor を再起動するかウィンドウをリロードして、設定が有効になっていることを確認します。

統合の確認

Cursor が Milvus MCP サーバーと正常に統合されたことを確認するには:

  1. Cursor Settings > MCP を開きます。
  2. 選択したモードに応じて、"milvus"、"milvus-sse"、または "milvus-streamable-http" がリストに表示されているか確認します。
  3. 関連するツール (例: milvus_list_collections、milvus_vector_search など) がリストされていることを確認します。
  4. サーバーが有効になっているがエラーが表示される場合は、以下のトラブルシューティングセクションを確認してください。

利用可能なツール

サーバーは以下のツールを提供します。

検索およびクエリ操作

  • milvus_text_search: 全文検索を使用してドキュメントを検索します

    • パラメータ:
      • collection_name: 検索するコレクションの名前
      • query_text: 検索するテキスト
      • limit: 返される結果の最大数 (デフォルト: 5)
      • output_fields: 結果に含めるフィールド
      • drop_ratio: 無視する低頻度語の割合 (0.0-1.0) (デフォルト: 0.2)

  • milvus_vector_search: コレクションに対してベクトル類似検索を実行します

    • パラメータ:
      • collection_name: 検索するコレクションの名前
      • vector: クエリベクトル
      • vector_field: ベクトル検索のフィールド名 (デフォルト: "vector")
      • limit: 返される結果の最大数 (デフォルト: 5)
      • output_fields: 結果に含めるフィールド
      • filter_expr: フィルタ式
      • metric_type: 距離メトリック (COSINE, L2, IP) (デフォルト: "COSINE")
      • radius: 範囲検索のオプションの下限 (デフォルト: None)
      • range_filter: 範囲検索のオプションの上限 (デフォルト: None)

  • milvus_hybrid_search: コレクションに対してハイブリッド検索を実行します

    • パラメータ:
      • collection_name: 検索するコレクションの名前
      • query_text: 検索用のテキストクエリ
      • text_field: テキスト検索のフィールド名
      • vector: テキストクエリのベクトル
      • vector_field: ベクトル検索のフィールド名
      • limit: 返される結果の最大数 (デフォルト: 5)
      • output_fields: 結果に含めるフィールド
      • filter_expr: フィルタ式
      • sparse_radius: スパース範囲検索のオプションの下限 (デフォルト: None)
      • sparse_range_filter: スパース範囲検索のオプションの上限 (デフォルト: None)
      • dense_radius: デンス範囲検索のオプションの下限 (デフォルト: None)
      • dense_range_filter: デンス範囲検索のオプションの上限 (デフォルト: None)

  • milvus_text_similarity_search: コレクションに対してテキスト類似検索を実行します

    注意: このツールは Milvus 2.6.0 以降でのみサポートされています。また、Milvus サーバー側で埋め込み関数を設定する必要があります。詳細は 埋め込み関数 を参照してください。

    • パラメータ:
      • collection_name: 検索するコレクションの名前
      • query_text: 類似検索用のテキストクエリ
      • anns_field: テキスト検索のフィールド名
      • limit: 返される結果の最大数 (デフォルト: 5)
      • output_fields: 結果に含めるフィールド
      • metric_type: 距離メトリック (COSINE, L2, IP) (デフォルト: "COSINE")
      • filter_expr: オプションのフィルタ式
      • radius: 範囲検索のオプションの下限 (デフォルト: None)
      • range_filter: 範囲検索のオプションの上限 (デフォルト: None)

  • milvus_query: フィルタ式を使用してコレクションをクエリします

    • パラメータ:
      • collection_name: クエリするコレクションの名前
      • filter_expr: フィルタ式 (例: 'age > 20')
      • output_fields: 結果に含めるフィールド
      • limit: 返される結果の最大数 (デフォルト: 10)

コレクション管理

  • milvus_list_collections: データベース内のすべてのコレクションをリストします

  • milvus_create_collection: クイックセットアップまたはカスタマイズされたスキーマで新しいコレクションを作成します

    • パラメータ:
      • collection_name: 新しいコレクションの名前
      • auto_id: ID を自動生成するかどうか (デフォルト: True)
      • dimension: ベクトル次元 (デフォルト: 768)。クイックセットアップ用で、field_schema が提供されている場合は無視されます
      • primary_field_name: プライマリフィールドの名前 (デフォルト: "id")。クイックセットアップ用で、field_schema が提供されている場合は無視されます
      • vector_field_name: ベクトルフィールドの名前 (デフォルト: "vector")。クイックセットアップ用で、field_schema が提供されている場合は無視されます
      • metric_type: メトリックタイプ (デフォルト: "COSINE")。クイックセットアップ用で、field_schema が提供されている場合は無視されます
      • field_schema: フィールドスキーマのリスト。各要素は以下のキーを持つ辞書です。
        • name: フィールドの名前
        • type: フィールドのタイプ
      • index_params: インデックスパラメータのオプションリスト。各要素は以下のキーを持つ辞書です。
        • field_name: インデックスを作成するフィールドの名前
        • index_type: インデックスタイプ
        • **kwargs: その他のオプションのインデックスパラメータ
      • other_kwargs: コレクション作成のための追加キーワード引数

  • milvus_load_collection: 検索とクエリのためにコレクションをメモリにロードします

    • パラメータ:
      • collection_name: ロードするコレクションの名前
      • replica_number: レプリカ数 (デフォルト: 1)

  • milvus_release_collection: メモリからコレクションを解放します

    • パラメータ:
      • collection_name: 解放するコレクションの名前

  • milvus_get_collection_info: 特定のコレクションのスキーマ、プロパティ、コレクション ID、その他のメタデータなどの詳細情報をリストします。

    • パラメータ:
      • collection_name: 詳細情報を取得するコレクションの名前

データ操作

  • milvus_insert_data: コレクションにデータを挿入します

    • パラメータ:
      • collection_name: コレクションの名前
      • data: フィールド名を値のリストにマッピングする辞書

  • milvus_delete_entities: フィルタ式に基づいてコレクションからエンティティを削除します

    • パラメータ:
      • collection_name: コレクションの名前
      • filter_expr: 削除するエンティティを選択するためのフィルタ式

環境変数

  • MILVUS_URI: Milvus サーバー URI (--milvus-uri の代わりに設定可能)
  • MILVUS_TOKEN: オプションの認証トークン
  • MILVUS_DB: データベース名 (デフォルト: "default")

開発

サーバーを直接実行するには:

uv run server.py --milvus-uri http://localhost:19530

例

Claude Desktop の使用

例 1: コレクションのリスト表示

What are the collections I have in my Milvus DB?

Claude は MCP を使用して、Milvus DB 上のこの情報を確認します。

I'll check what collections are available in your Milvus database.

Here are the collections in your Milvus database:

1. rag_demo
2. test
3. chat_messages
4. text_collection
5. image_collection
6. customized_setup
7. streaming_rag_demo

例 2: ドキュメントの検索

Find documents in my text_collection that mention "machine learning"

Claude は Milvus の全文検索機能を使用して、関連ドキュメントを検索します。

I'll search for documents about machine learning in your text_collection.

> View result from milvus-text-search from milvus (local)

Here are the documents I found that mention machine learning:
[Results will appear here based on your actual data]

Cursor の使用

例: コレクションの作成

Cursor で次のように尋ねることができます。

Create a new collection called 'articles' in Milvus with fields for title (string), content (string), and a vector field (128 dimensions)

Cursor は MCP サーバーを使用してこの操作を実行します。

I'll create a new collection called 'articles' with the specified fields.

Collection 'articles' has been created successfully with the following schema:
- title: string
- content: string
- vector: float vector[128]

トラブルシューティング

一般的な問題

接続エラー

"Failed to connect to Milvus server" のようなエラーが表示された場合:

  1. Milvus インスタンスが稼働していることを確認します: docker ps (Docker を使用している場合)
  2. 設定内の URI が正しいことを確認します
  3. 接続をブロックするファイアウォールルールがないことを確認します
  4. URI で localhost の代わりに 127.0.0.1 を使用してみてください

認証の問題

認証エラーが表示された場合:

  1. MILVUS_TOKEN が正しいことを確認します
  2. Milvus インスタンスが認証を必要とするかどうかを確認します
  3. 実行しようとしている操作に対する適切な権限があることを確認します

ツールが見つからない場合

Claude Desktop や Cursor に MCP ツールが表示されない場合:

  1. アプリケーションを再起動します
  2. サーバーログにエラーがないか確認します
  3. MCP サーバーが正しく稼働していることを確認します
  4. MCP 設定の更新ボタンを押します (Cursor の場合)

ヘルプの利用

問題が解決しない場合:

  1. GitHub Issues で同様の問題を確認します
  2. Milvus コミュニティ Discord に参加してサポートを受けます
  3. 問題に関する詳細情報を添えて新しい Issue を作成します