Milvus

Milvus 用 MCP サーバー

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

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

注： このリポジトリは https://github.com/zilliztech/mcp-server-milvus.git のフォークで、さまざまな改善が加えられています。また、uvx による実行がサポートされているため、インストールせずに簡単に実行できます。

前提条件

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

• Python 3.10 以降
• 起動中の Milvus インスタンス（ローカルまたはリモート）
• uv がインストールされていること（サーバーの実行に推奨）
• npx がインストールされていること（MCP Inspector でのテスト用）

使用方法

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

サーバーの実行

次のコマンドを使用して Milvus 用 MCP サーバーを実行できます。http://localhost:19530 は、お使いの Milvus サーバー URI に置き換えてください。

uvx mcp-server-milvus --milvus-uri http://localhost:19530

または、プロジェクトディレクトリにある .env ファイルで環境変数を設定し、次の uvx コマンドでサーバーを実行できます。

# Create a .env file with your Milvus configuration
cat > .env <<EOF
MILVUS_URI=http://localhost:19530
MILVUS_TOKEN=root:Milvus
MILVUS_DB=default
EOF

# Run the server with the .env file
uvx --env-file .env mcp-server-milvus

実行モード

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

Stdio モード（デフォルト）

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

• 使用方法：

  uvx mcp-server-milvus@latest --milvus-uri http://localhost:19530
  

SSE モード

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

• 使用方法：

  uvx mcp-server-milvus@latest --sse --milvus-uri http://localhost:19530
  

  • --sse：SSE モードを有効にします。

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

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

  npx @modelcontextprotocol/inspector --transport sse --server-url http://localhost:8000/sse
  

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

  % npx @modelcontextprotocol/inspector --transport sse --server-url http://localhost:8000/sse
  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 サーバーは、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": []
    }
  }
}

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": "uvx",
      "args": [
        "mcp-server-milvus@latest",
        "--milvus-uri",
        "http://localhost:19530"
      ]
    }
  }
}

4. 変更を適用するため、Claude Desktop を再起動します。

Cursor での使用

Cursor は MCP ツールにも対応しています。以下の手順に従って、Milvus MCP サーバーを Cursor に統合できます。

統合手順

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

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

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

   • Type：stdio を選択します（コマンドを実行するため）
   • Name：milvus
   • Command：uvx mcp-server-milvus@latest --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": "uvx",
          "args": [
            "mcp-server-milvus@latest",
            "--milvus-uri",
            "http://127.0.0.1:19530"
          ]
       }
     }
   }
   

SSE モードの場合：

1. 以下のコマンドを実行してサービスを起動します：

   uv run mcp-server-milvus --sse --milvus-uri http://your_sse_host
   

   注：http://your_sse_host を実際の SSE ホストアドレスに置き換えてください。

2. サービスが起動して稼働したら、以下の内容で mcp.json ファイルを上書きします：

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

統合の完了

上記の手順が完了したら、設定を反映するために Cursor を再起動するか、ウィンドウを再読み込みしてください。

統合の確認

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

開発

開発中のテスト

MCP Inspector を使用して、サーバーをローカルでテストするには：

npx @modelcontextprotocol/inspector uvx mcp-server-milvus@latest

使用例

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. 実行しようとしている操作に必要な権限があることを確認します

ツールが見つからない

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

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

ヘルプの利用

問題が解決しない場合：

1. 同様の問題がないか、GitHub Issues を確認します
2. サポートについては、Zilliz Community Discord に参加します
3. 問題の詳細を記載して、新しい issue を作成します