Milvus MCP Server

resmi

Cari, kueri, dan berinteraksi dengan data di Milvus Vector Database Anda.

GitHub
233

Dokumentasi

Server MCP untuk Milvus

Model Context Protocol (MCP) adalah protokol terbuka yang memungkinkan integrasi mulus antara aplikasi LLM dengan sumber data dan alat eksternal. Baik Anda membangun IDE bertenaga AI, meningkatkan antarmuka obrolan, atau membuat alur kerja AI kustom, MCP menyediakan cara standar untuk menghubungkan LLM dengan konteks yang mereka butuhkan.

Repositori ini berisi server MCP yang menyediakan akses ke fungsionalitas basis data vektor Milvus.

MCP with Milvus

Prasyarat

Sebelum menggunakan server MCP ini, pastikan Anda memiliki:

  • Python 3.10 atau lebih tinggi
  • Instans Milvus yang berjalan (lokal atau jarak jauh)
  • uv terinstal (disarankan untuk menjalankan server)

Penggunaan

Cara yang disarankan untuk menggunakan server MCP ini adalah menjalankannya langsung dengan uv tanpa instalasi. Ini adalah cara Claude Desktop dan Cursor dikonfigurasi untuk menggunakannya dalam contoh di bawah.

Jika Anda ingin mengkloning repositori:

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

Kemudian Anda dapat menjalankan server secara langsung:

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

Atau, Anda dapat mengubah file .env di direktori src/mcp_server_milvus/ untuk mengatur variabel lingkungan dan menjalankan server dengan perintah berikut:

uv run src/mcp_server_milvus/server.py

Penting: file .env akan memiliki prioritas lebih tinggi daripada argumen baris perintah.

Mode Berjalan

Server mendukung dua mode berjalan: stdio (default) dan SSE (Server-Sent Events).

Mode Stdio (Default)

  • Deskripsi: Berkomunikasi dengan klien melalui input/output standar. Ini adalah mode default jika tidak ada mode yang ditentukan.

  • Penggunaan:

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

Mode SSE

  • Deskripsi: Menggunakan HTTP Server-Sent Events untuk komunikasi. Mode ini memungkinkan banyak klien terhubung melalui HTTP dan cocok untuk aplikasi berbasis web.

  • Penggunaan:

    uv run src/mcp_server_milvus/server.py --sse --milvus-uri http://localhost:19530 --port 8000
    • --sse: Mengaktifkan mode SSE.
    • --port: Menentukan port untuk server SSE (default: 8000).

  • Debugging dalam Mode SSE:

    Jika Anda ingin melakukan debug dalam mode SSE, setelah memulai layanan SSE, masukkan perintah berikut:

    mcp dev src/mcp_server_milvus/server.py

    Outputnya akan mirip dengan:

    % 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 🚀

    Anda kemudian dapat mengakses Inspektur MCP di http://127.0.0.1:6274 untuk pengujian.

Mode HTTP Streamable

  • Deskripsi: Menggunakan HTTP dengan dukungan streaming untuk komunikasi. Ini adalah transport yang direkomendasikan untuk deployment produksi dan mendukung operasi stateful maupun stateless.

  • Penggunaan:

    uv run src/mcp_server_milvus/server.py --streamable-http --milvus-uri http://localhost:19530 --port 8000
    • --streamable-http: Mengaktifkan mode HTTP Streamable.
    • --port: Menentukan port untuk server (default: 8000).
    • --stateless: Flag opsional untuk mode stateless (tanpa persistensi sesi).

  • Mode Stateless:

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

Aplikasi yang Didukung

Server MCP ini dapat digunakan dengan berbagai aplikasi LLM yang mendukung Model Context Protocol:

  • Claude Desktop: Aplikasi desktop Anthropic untuk Claude
  • Cursor: Editor kode bertenaga AI dengan dukungan MCP
  • Klien MCP kustom: Aplikasi apa pun yang mengimplementasikan spesifikasi klien MCP

Penggunaan dengan Claude Desktop

Konfigurasi untuk Mode Berbeda

Konfigurasi Mode SSE

Ikuti langkah-langkah ini untuk mengonfigurasi Claude Desktop untuk mode SSE:

  1. Instal Claude Desktop dari https://claude.ai/download.
  2. Buka file konfigurasi Claude Desktop Anda:
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  3. Tambahkan konfigurasi berikut untuk mode SSE:
{
  "mcpServers": {
    "milvus-sse": {
      "url": "http://your_sse_host:port/sse",
      "disabled": false,
      "autoApprove": []
    }
  }
}

Konfigurasi Mode HTTP Streamable

{
  "mcpServers": {
    "milvus-streamable-http": {
      "url": "http://your_host:port/mcp",
      "disabled": false,
      "autoApprove": []
    }
  }
}
  1. Mulai ulang Claude Desktop untuk menerapkan perubahan.

Konfigurasi Mode Stdio

Untuk mode stdio, ikuti langkah-langkah ini:

  1. Instal Claude Desktop dari https://claude.ai/download.
  2. Buka file konfigurasi Claude Desktop Anda:
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  3. Tambahkan konfigurasi berikut untuk mode 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. Mulai ulang Claude Desktop untuk menerapkan perubahan.

Penggunaan dengan Cursor

Cursor juga mendukung MCP. Anda dapat mengintegrasikan server MCP Milvus Anda dengan Cursor dengan mengikuti langkah-langkah ini:

Langkah Integrasi

  1. Buka Cursor Settings > MCP
  2. Klik Add new global MCP server
  3. Setelah mengklik, secara otomatis akan mengarahkan Anda ke file mcp.json, yang akan dibuat jika belum ada

Mengonfigurasi File mcp.json

Untuk Mode Stdio:

Timpa file mcp.json dengan konten berikut:

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

Untuk Mode SSE:

  1. Mulai layanan dengan menjalankan perintah berikut:

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

    Catatan: Ganti http://your_sse_host dengan alamat host SSE Anda yang sebenarnya dan port dengan nomor port spesifik yang Anda gunakan.

  2. Setelah layanan berjalan, timpa file mcp.json dengan konten berikut:

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

Untuk Mode HTTP Streamable:

  1. Mulai layanan:

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

  2. Perbarui mcp.json:

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

Menyelesaikan Integrasi

Setelah menyelesaikan langkah-langkah di atas, mulai ulang Cursor atau muat ulang jendela untuk memastikan konfigurasi berlaku.

Memverifikasi Integrasi

Untuk memverifikasi bahwa Cursor telah berhasil terintegrasi dengan server MCP Milvus Anda:

  1. Buka Cursor Settings > MCP
  2. Periksa apakah "milvus", "milvus-sse", atau "milvus-streamable-http" muncul dalam daftar (tergantung mode yang Anda pilih)
  3. Konfirmasi bahwa alat yang relevan tercantum (misalnya, milvus_list_collections, milvus_vector_search, dll.)
  4. Jika server diaktifkan tetapi menunjukkan kesalahan, periksa bagian Pemecahan Masalah di bawah

Alat yang Tersedia

Server menyediakan alat-alat berikut:

Operasi Pencarian dan Kueri

  • milvus_text_search: Mencari dokumen menggunakan pencarian teks lengkap

    • Parameter:
      • collection_name: Nama koleksi untuk dicari
      • query_text: Teks yang akan dicari
      • limit: Jumlah maksimum hasil yang dikembalikan (default: 5)
      • output_fields: Bidang yang disertakan dalam hasil
      • drop_ratio: Proporsi istilah frekuensi rendah yang diabaikan (0.0-1.0) (default: 0.2)

  • milvus_vector_search: Melakukan pencarian kemiripan vektor pada koleksi

    • Parameter:
      • collection_name: Nama koleksi untuk dicari
      • vector: Vektor kueri
      • vector_field: Nama bidang untuk pencarian vektor (default: "vector")
      • limit: Jumlah maksimum hasil yang dikembalikan (default: 5)
      • output_fields: Bidang yang disertakan dalam hasil
      • filter_expr: Ekspresi filter
      • metric_type: Metrik jarak (COSINE, L2, IP) (default: "COSINE")
      • radius: Batas bawah opsional untuk pencarian rentang (default: None)
      • range_filter: Batas atas opsional untuk pencarian rentang (default: None)

  • milvus_hybrid_search: Melakukan pencarian hibrida pada koleksi

    • Parameter:
      • collection_name: Nama koleksi untuk dicari
      • query_text: Kueri teks untuk pencarian
      • text_field: Nama bidang untuk pencarian teks
      • vector: Vektor dari kueri teks
      • vector_field: Nama bidang untuk pencarian vektor
      • limit: Jumlah maksimum hasil yang dikembalikan (default: 5)
      • output_fields: Bidang yang disertakan dalam hasil
      • filter_expr: Ekspresi filter
      • sparse_radius: Batas bawah opsional untuk pencarian rentang sparse (default: None)
      • sparse_range_filter: Batas atas opsional untuk pencarian rentang sparse (default: None)
      • dense_radius: Batas bawah opsional untuk pencarian rentang dense (default: None)
      • dense_range_filter: Batas atas opsional untuk pencarian rentang dense (default: None)

  • milvus_text_similarity_search: Melakukan pencarian kemiripan teks pada koleksi

    Catatan: Alat ini hanya didukung di Milvus 2.6.0 ke atas. Dan Anda perlu mengatur fungsi embedding di server Milvus. Lihat Fungsi Embedding untuk detail lebih lanjut.

    • Parameter:
      • collection_name: Nama koleksi untuk dicari
      • query_text: Kueri teks untuk pencarian kemiripan
      • anns_field: Nama bidang untuk pencarian teks
      • limit: Jumlah maksimum hasil yang dikembalikan (default: 5)
      • output_fields: Bidang yang disertakan dalam hasil
      • metric_type: Metrik jarak (COSINE, L2, IP) (default: "COSINE")
      • filter_expr: Ekspresi filter opsional
      • radius: Batas bawah opsional untuk pencarian rentang (default: None)
      • range_filter: Batas atas opsional untuk pencarian rentang (default: None)

  • milvus_query: Kueri koleksi menggunakan ekspresi filter

    • Parameter:
      • collection_name: Nama koleksi untuk dikueri
      • filter_expr: Ekspresi filter (mis. 'age > 20')
      • output_fields: Bidang yang disertakan dalam hasil
      • limit: Jumlah maksimum hasil yang dikembalikan (default: 10)

Manajemen Koleksi

  • milvus_list_collections: Mencantumkan semua koleksi dalam basis data

  • milvus_create_collection: Membuat koleksi baru dengan pengaturan cepat atau skema kustom

    • Parameter:
      • collection_name: Nama untuk koleksi baru
      • auto_id: apakah akan menghasilkan id secara otomatis, default True
      • dimension: dimensi vektor, default 768; untuk pengaturan cepat dan akan diabaikan jika field_schema disediakan
      • primary_field_name: nama bidang utama, default "id"; untuk pengaturan cepat dan akan diabaikan jika field_schema disediakan
      • vector_field_name: nama bidang vektor, default "vector"; untuk pengaturan cepat dan akan diabaikan jika field_schema disediakan
      • metric_type: tipe metrik, default "COSINE"; untuk pengaturan cepat dan akan diabaikan jika field_schema disediakan
      • field_schema: Daftar skema bidang, setiap elemen adalah kamus dengan kunci berikut:
        • name: nama bidang
        • type: tipe bidang
      • index_params: Daftar opsional parameter indeks, setiap elemen adalah kamus dengan kunci berikut:
        • field_name: nama bidang yang akan diindeks
        • index_type: tipe indeks
        • **kwargs: parameter indeks opsional lainnya
      • other_kwargs: Argumen kata kunci tambahan untuk pembuatan koleksi

  • milvus_load_collection: Memuat koleksi ke dalam memori untuk pencarian dan kueri

    • Parameter:
      • collection_name: Nama koleksi yang akan dimuat
      • replica_number: Jumlah replika (default: 1)

  • milvus_release_collection: Melepaskan koleksi dari memori

    • Parameter:
      • collection_name: Nama koleksi yang akan dilepaskan

  • milvus_get_collection_info: Mencantumkan informasi detail seperti skema, properti, ID koleksi, dan metadata lainnya dari koleksi tertentu.

    • Parameter:
      • collection_name: Nama koleksi untuk mendapatkan informasi detail

Operasi Data

  • milvus_insert_data: Memasukkan data ke dalam koleksi

    • Parameter:
      • collection_name: Nama koleksi
      • data: Kamus yang memetakan nama bidang ke daftar nilai

  • milvus_delete_entities: Menghapus entitas dari koleksi berdasarkan ekspresi filter

    • Parameter:
      • collection_name: Nama koleksi
      • filter_expr: Ekspresi filter untuk memilih entitas yang akan dihapus

Variabel Lingkungan

  • MILVUS_URI: URI server Milvus (dapat diatur sebagai pengganti --milvus-uri)
  • MILVUS_TOKEN: Token autentikasi opsional
  • MILVUS_DB: Nama basis data (default "default")

Pengembangan

Untuk menjalankan server secara langsung:

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

Contoh

Menggunakan Claude Desktop

Contoh 1: Mencantumkan Koleksi

What are the collections I have in my Milvus DB?

Claude kemudian akan menggunakan MCP untuk memeriksa informasi ini di DB Milvus Anda.

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

Contoh 2: Mencari Dokumen

Find documents in my text_collection that mention "machine learning"

Claude akan menggunakan kemampuan pencarian teks lengkap Milvus untuk menemukan dokumen yang relevan:

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]

Menggunakan Cursor

Contoh: Membuat Koleksi

Di Cursor, Anda dapat bertanya:

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

Cursor akan menggunakan server MCP untuk menjalankan operasi ini:

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]

Pemecahan Masalah

Masalah Umum

Kesalahan Koneksi

Jika Anda melihat kesalahan seperti "Failed to connect to Milvus server":

  1. Verifikasi bahwa instans Milvus Anda sedang berjalan: docker ps (jika menggunakan Docker)
  2. Periksa apakah URI sudah benar dalam konfigurasi Anda
  3. Pastikan tidak ada aturan firewall yang memblokir koneksi
  4. Coba gunakan 127.0.0.1 alih-alih localhost di URI

Masalah Autentikasi

Jika Anda melihat kesalahan autentikasi:

  1. Verifikasi bahwa MILVUS_TOKEN Anda sudah benar
  2. Periksa apakah instans Milvus Anda memerlukan autentikasi
  3. Pastikan Anda memiliki izin yang tepat untuk operasi yang ingin Anda lakukan

Alat Tidak Ditemukan

Jika alat MCP tidak muncul di Claude Desktop atau Cursor:

  1. Mulai ulang aplikasi
  2. Periksa log server untuk melihat adanya kesalahan
  3. Verifikasi bahwa server MCP berjalan dengan benar
  4. Tekan tombol segarkan di pengaturan MCP (untuk Cursor)

Mendapatkan Bantuan

Jika Anda terus mengalami masalah:

  1. Periksa GitHub Issues untuk masalah serupa
  2. Bergabunglah dengan Milvus Community Discord untuk mendapatkan dukungan
  3. Ajukan isu baru dengan informasi terperinci tentang masalah Anda