Milvus 用 MCP サーバー

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

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

前提条件

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

• Python 3.10以上

• 実行中のMilvusインスタンス (ローカルまたはリモート)

• uvがインストールされている（サーバーの実行に推奨）

Related MCP server: MCP Database Server

使用法

この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サーバー送信イベントを使用します。このモードでは、複数のクライアントが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 にアクセスできます。

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

この MCP サーバーは、モデル コンテキスト プロトコルをサポートするさまざまな LLM アプリケーションで使用できます。

• Claude Desktop : Claude 用の Anthropic のデスクトップ アプリケーション

• カーソル: 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": []
    }
  }
}

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

統合の完了

上記の手順を完了したら、設定が有効になるようにカーソルを再起動するか、ウィンドウを再読み込みします。

統合の検証

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

1. Cursor Settingsを開く > MCP

2. リストに「milvus」または「milvus-sse」が表示されているかどうかを確認します（選択したモードによって異なります）

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 : 結果に含めるフィールド

    • filter_expr : フィルター式

    • metric_type : 距離メトリック（COSINE、L2、IP）（デフォルト: "COSINE"）

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

  • パラメータ:

    • collection_name : 検索するコレクションの名前

    • query_text : 検索用のテキストクエリ

    • text_field : テキスト検索のフィールド名

    • vector : テキストクエリのベクトル

    • vector_field : ベクトル検索のフィールド名

    • limit : 返される結果の最大数

    • output_fields : 結果に含めるフィールド

    • filter_expr : フィルター式

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

  • パラメータ:

    • collection_name : クエリするコレクションの名前

    • filter_expr : フィルター式（例：'age > 20'）

    • output_fields : 結果に含めるフィールド

    • limit : 返される結果の最大数（デフォルト: 10）

コレクション管理

• milvus_list_collections : データベース内のすべてのコレクションを一覧表示する

• milvus_create_collection : 指定されたスキーマで新しいコレクションを作成する

  • パラメータ:

    • collection_name : 新しいコレクションの名前

    • collection_schema : コレクションスキーマ定義

    • index_params : オプションのインデックスパラメータ

• 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デスクトップの使用

例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"

クロードは、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]

カーソルの使用

例: コレクションの作成

カーソルでは、次のことを尋ねることができます。

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

カーソルは 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]

トラブルシューティング

よくある問題

接続エラー

「Milvus サーバーに接続できませんでした」などのエラーが表示された場合:

1. Milvusインスタンスが実行中であることを確認します: docker ps (Dockerを使用している場合)

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設定の更新ボタンを押します（カーソル用）

ヘルプの取得

問題が引き続き発生する場合:

1. 同様の問題についてはGitHub Issuesを確認してください

2. サポートを受けるには、 ZillizコミュニティDiscordに参加してください

3. 問題に関する詳細情報を記載した新しい問題を提出してください