MCP Server for Milvus

Milvus 用 MCP サーバー

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

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

前提条件

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

• Python 3.10 以降
• 実行中の Milvus インスタンス（ローカルまたはリモート）
• uv のインストール（サーバーの実行に推奨）

使用方法

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

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

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

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

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

対応アプリケーション

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

• Claude Desktop：Claude 用の Anthropic のデスクトップアプリケーション
• Cursor：Composer 機能で MCP に対応する AI 搭載コードエディター
• カスタム MCP クライアント：MCP クライアント仕様を実装するあらゆるアプリケーション

Claude Desktop での使用方法

1. https://claude.ai/download から Claude Desktop をインストールします

2. Claude Desktop の設定を開きます。

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json

3. 以下の設定を追加します。

{
  "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"
      ]
    }
  }
}

4. Claude Desktop を再起動します

Cursor での使用方法

Cursor は Composer の Agent 機能を通じて MCP ツールにも対応しています。次の 2 つの方法で、Milvus MCP サーバーを Cursor に追加できます。

方法 1：Cursor の設定 UI を使用する

1. Cursor Settings > Features > MCP に移動します

2. + Add New MCP Server ボタンをクリックします

3. フォームに入力します。

   • Type：stdio を選択します（コマンドを実行するため）
   • Name：milvus
   • Command：/PATH/TO/uv --directory /path/to/mcp-server-milvus/src/mcp_server_milvus run server.py --milvus-uri http://127.0.0.1:19530

   ⚠️ 注：DNS 解決に関する問題を避けるため、localhost ではなく 127.0.0.1 を使用してください。

方法 2：プロジェクト固有の設定を使用する（推奨）

プロジェクトのルートに .cursor/mcp.json ファイルを作成します。

1. プロジェクトのルートに .cursor ディレクトリを作成します。

   mkdir -p /path/to/your/project/.cursor
   

2. 以下の内容で 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"
         ]
       }
     }
   }
   

3. Cursor を再起動するか、ウィンドウを再読み込みします

サーバーを追加した後、ツールの一覧を表示するには、MCP 設定の更新ボタンを押す必要がある場合があります。Composer Agent は、クエリに関連する場合に Milvus ツールを自動的に使用します。

統合の確認

Cursor が Milvus MCP サーバーと正常に統合されたことを確認するには、次の手順を実行します。

1. Cursor Settings > Features > MCP を開きます
2. MCP サーバーの一覧に「Milvus」が表示されていることを確認します
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）

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

  • パラメーター：
    • collection_name: 検索するコレクション名
    • vector: クエリベクトル
    • vector_field: 検索対象のベクトルを含むフィールド（デフォルト："vector"）
    • limit: 最大結果数（デフォルト：5）
    • output_fields: 結果に含めるフィールド
    • metric_type: 距離メトリック（COSINE、L2、IP）（デフォルト："COSINE"）
    • filter_expr: 任意のフィルター式

• milvus-hybrid-search: ベクトル類似度検索と属性フィルタリングを組み合わせたハイブリッド検索を実行します

  • パラメーター：
    • collection_name: 検索するコレクション名
    • vector: クエリベクトル
    • vector_field: 検索対象のベクトルを含むフィールド（デフォルト："vector"）
    • filter_expr: メタデータのフィルター式
    • limit: 最大結果数（デフォルト：5）
    • output_fields: 結果に含めるフィールド
    • metric_type: 距離メトリック（COSINE、L2、IP）（デフォルト："COSINE"）

• milvus-multi-vector-search: 複数のクエリベクトルを使用してベクトル類似検索を実行します

  • パラメーター：
    • collection_name: 検索するコレクション名
    • vectors: クエリベクトルのリスト
    • vector_field: 検索対象のベクトルを含むフィールド（デフォルト："vector"）
    • limit: クエリごとの最大結果数（デフォルト：5）
    • output_fields: 結果に含めるフィールド
    • metric_type: 距離メトリック（COSINE、L2、IP）（デフォルト："COSINE"）
    • filter_expr: 任意のフィルター式

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

  • パラメーター：
    • collection_name: クエリ対象のコレクション名
    • filter_expr: フィルター式（例：'age > 20'）
    • output_fields: 結果に含めるフィールド
    • limit: 最大結果数（デフォルト：10）

• milvus-count: コレクション内のエンティティ数をカウントします

  • パラメーター：
    • collection_name: コレクション名
    • filter_expr: 任意のフィルター式

コレクション管理

• milvus-list-collections: データベース内のすべてのコレクションを一覧表示します

• milvus-collection-info: コレクションの詳細情報を取得します

  • パラメーター：
    • collection_name: コレクション名

• milvus-get-collection-stats: コレクションの統計情報を取得します

  • パラメーター：
    • collection_name: コレクション名

• milvus-create-collection: 指定したスキーマで新しいコレクションを作成します

  • パラメーター：
    • collection_name: 新しいコレクションの名前
    • schema: コレクションのスキーマ定義
    • index_params: 任意のインデックスパラメーター

• milvus-load-collection: 検索およびクエリ用にコレクションをメモリに読み込みます

  • パラメーター：
    • collection_name: 読み込むコレクション名
    • replica_number: レプリカ数（デフォルト：1）

• milvus-release-collection: コレクションをメモリから解放します

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

• milvus-get-query-segment-info: クエリセグメントに関する情報を取得します

  • パラメーター：
    • collection_name: コレクション名

• milvus-get-collection-loading-progress: コレクションの読み込み進捗を取得します

  • パラメーター：
    • collection_name: コレクション名

データ操作

• milvus-insert-data：コレクションにデータを挿入します

  • パラメーター：
    • collection_name：コレクション名
    • data：フィールド名を値のリストに対応付ける辞書

• milvus-bulk-insert：パフォーマンスを向上させるため、データをバッチ単位で挿入します

  • パラメーター：
    • collection_name：コレクション名
    • data：フィールド名を値のリストに対応付ける辞書
    • batch_size：バッチごとのレコード数（デフォルト：1000）

• milvus-upsert-data：コレクションにデータをアップサートします（存在しない場合は挿入し、存在する場合は更新します）

  • パラメーター：
    • collection_name：コレクション名
    • data：フィールド名を値のリストに対応付ける辞書

• milvus-delete-entities：フィルター式に基づいて、コレクションからエンティティを削除します

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

• milvus-create-dynamic-field：既存のコレクションに動的フィールドを追加します

  • パラメーター：
    • collection_name：コレクション名
    • field_name：新しいフィールドの名前
    • data_type：フィールドのデータ型
    • description：任意の説明

インデックス管理

• milvus-create-index：ベクトルフィールドにインデックスを作成します

  • パラメーター：
    • collection_name：コレクション名
    • field_name：インデックスを作成するフィールド
    • index_type：インデックスの種類（IVF_FLAT、HNSW など）（デフォルト："IVF_FLAT"）
    • metric_type：距離尺度（COSINE、L2、IP）（デフォルト："COSINE"）
    • params：追加のインデックスパラメーター

• milvus-get-index-info：コレクション内のインデックスに関する情報を取得します

  • パラメーター：
    • collection_name：コレクション名
    • field_name：インデックス情報を取得する特定のフィールド（任意）

環境変数

• 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.

> View result from milvus-list-collections from milvus (local)

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 の Composer で、次のように依頼できます：

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.

> View result from milvus-create-collection from milvus (local)

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 を使用している場合は、docker ps を実行します
2. 設定内の URI が正しいことを確認します
3. 接続をブロックするファイアウォールルールがないことを確認します
4. URI の localhost を 127.0.0.1 に置き換えてみます

認証の問題

認証エラーが表示される場合：

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

ツールが見つからない

MCP ツールが Claude Desktop または Cursor に表示されない場合：

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

ヘルプの利用

問題が解決しない場合：

1. 類似の問題がないか、GitHub の Issue を確認します
2. サポートを受けるには、Zilliz Community Discord に参加します
3. 問題の詳細を記載して、新しい Issue を作成します