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/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 経由で複数のクライアントが接続でき、ウェブベースのアプリケーションに適しています。

• 使用方法：

  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 にアクセスしてテストできます。

Streamable HTTP モード

• 説明：通信にストリーミング対応の HTTP を使用します。このモードは本番環境へのデプロイに推奨されるトランスポートで、ステートフルとステートレスの両方の動作に対応しています。

• 使用方法：

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

  • --streamable-http：Streamable 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：Claude 用の Anthropic デスクトップアプリケーション
• 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": []
    }
  }
}

Streamable HTTP モードの設定

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

4. 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"
      ]
    }
  }
}

4. 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": []
         }
       }
   }
   

Streamable 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 の Issueを確認します
2. サポートを受けるには、Milvus コミュニティの Discordに参加します
3. 問題の詳細情報を添えて、新しい Issue を作成します