Milvus MCP Server

offiziell

Durchsuchen, abfragen und interagieren Sie mit Daten in Ihrer Milvus-Vektordatenbank.

GitHub
233

Dokumentation

MCP-Server für Milvus

Das Model Context Protocol (MCP) ist ein offenes Protokoll, das eine nahtlose Integration zwischen LLM-Anwendungen und externen Datenquellen und Werkzeugen ermöglicht. Ob Sie eine KI-gestützte IDE entwickeln, eine Chat-Schnittstelle erweitern oder benutzerdefinierte KI-Workflows erstellen – MCP bietet eine standardisierte Möglichkeit, LLMs mit dem benötigten Kontext zu verbinden.

Dieses Repository enthält einen MCP-Server, der Zugriff auf die Vektordatenbank-Funktionalität von Milvus bietet.

MCP with Milvus

Voraussetzungen

Stellen Sie vor der Nutzung dieses MCP-Servers sicher, dass Sie Folgendes haben:

  • Python 3.10 oder höher
  • Eine laufende Milvus-Instanz (lokal oder remote)
  • uv installiert (empfohlen für die Ausführung des Servers)

Nutzung

Die empfohlene Methode zur Nutzung dieses MCP-Servers ist die direkte Ausführung mit uv ohne Installation. So werden sowohl Claude Desktop als auch Cursor in den folgenden Beispielen für die Nutzung konfiguriert.

Wenn Sie das Repository klonen möchten:

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

Dann können Sie den Server direkt ausführen:

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

Alternativ können Sie die .env-Datei im Verzeichnis src/mcp_server_milvus/ ändern, um die Umgebungsvariablen zu setzen, und den Server mit folgendem Befehl ausführen:

uv run src/mcp_server_milvus/server.py

Wichtig: Die .env-Datei hat eine höhere Priorität als die Befehlszeilenargumente.

Ausführungsmodi

Der Server unterstützt zwei Ausführungsmodi: stdio (Standard) und SSE (Server-Sent Events).

Stdio-Modus (Standard)

  • Beschreibung: Kommuniziert mit dem Client über Standardeingabe/-ausgabe. Dies ist der Standardmodus, wenn kein Modus angegeben ist.

  • Nutzung:

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

SSE-Modus

  • Beschreibung: Verwendet HTTP Server-Sent Events für die Kommunikation. Dieser Modus ermöglicht mehreren Clients die Verbindung über HTTP und eignet sich für webbasierte Anwendungen.

  • Nutzung:

    uv run src/mcp_server_milvus/server.py --sse --milvus-uri http://localhost:19530 --port 8000
    • --sse: Aktiviert den SSE-Modus.
    • --port: Gibt den Port für den SSE-Server an (Standard: 8000).

  • Debugging im SSE-Modus:

    Wenn Sie im SSE-Modus debuggen möchten, geben Sie nach dem Start des SSE-Dienstes folgenden Befehl ein:

    mcp dev src/mcp_server_milvus/server.py

    Die Ausgabe wird ähnlich sein wie:

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

    Sie können dann auf den MCP Inspector unter http://127.0.0.1:6274 zum Testen zugreifen.

Streamable HTTP-Modus

  • Beschreibung: Verwendet HTTP mit Streaming-Unterstützung für die Kommunikation. Dies ist der empfohlene Transport für Produktionsumgebungen und unterstützt sowohl zustandsbehafteten als auch zustandslosen Betrieb.

  • Nutzung:

    uv run src/mcp_server_milvus/server.py --streamable-http --milvus-uri http://localhost:19530 --port 8000
    • --streamable-http: Aktiviert den Streamable HTTP-Modus.
    • --port: Gibt den Port für den Server an (Standard: 8000).
    • --stateless: Optionales Flag für den zustandslosen Modus (keine Sitzungspersistenz).

  • Zustandsloser Modus:

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

Unterstützte Anwendungen

Dieser MCP-Server kann mit verschiedenen LLM-Anwendungen verwendet werden, die das Model Context Protocol unterstützen:

  • Claude Desktop: Anthropics Desktop-Anwendung für Claude
  • Cursor: KI-gestützter Code-Editor mit MCP-Unterstützung
  • Benutzerdefinierte MCP-Clients: Jede Anwendung, die die MCP-Client-Spezifikation implementiert

Nutzung mit Claude Desktop

Konfiguration für verschiedene Modi

SSE-Modus-Konfiguration

Befolgen Sie diese Schritte, um Claude Desktop für den SSE-Modus zu konfigurieren:

  1. Installieren Sie Claude Desktop von https://claude.ai/download.
  2. Öffnen Sie Ihre Claude Desktop-Konfigurationsdatei:
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  3. Fügen Sie die folgende Konfiguration für den SSE-Modus hinzu:
{
  "mcpServers": {
    "milvus-sse": {
      "url": "http://your_sse_host:port/sse",
      "disabled": false,
      "autoApprove": []
    }
  }
}

Streamable HTTP-Modus-Konfiguration

{
  "mcpServers": {
    "milvus-streamable-http": {
      "url": "http://your_host:port/mcp",
      "disabled": false,
      "autoApprove": []
    }
  }
}
  1. Starten Sie Claude Desktop neu, um die Änderungen zu übernehmen.

Stdio-Modus-Konfiguration

Für den Stdio-Modus befolgen Sie diese Schritte:

  1. Installieren Sie Claude Desktop von https://claude.ai/download.
  2. Öffnen Sie Ihre Claude Desktop-Konfigurationsdatei:
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  3. Fügen Sie die folgende Konfiguration für den Stdio-Modus hinzu:
{
  "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. Starten Sie Claude Desktop neu, um die Änderungen zu übernehmen.

Nutzung mit Cursor

Cursor unterstützt ebenfalls MCP-Werkzeuge. Sie können Ihren Milvus MCP-Server mit Cursor integrieren, indem Sie diese Schritte befolgen:

Integrationsschritte

  1. Öffnen Sie Cursor Settings > MCP
  2. Klicken Sie auf Add new global MCP server
  3. Nach dem Klicken werden Sie automatisch zur Datei mcp.json weitergeleitet, die erstellt wird, falls sie nicht existiert

Konfigurieren der Datei mcp.json

Für den Stdio-Modus:

Überschreiben Sie die Datei mcp.json mit folgendem Inhalt:

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

Für den SSE-Modus:

  1. Starten Sie den Dienst, indem Sie folgenden Befehl ausführen:

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

    Hinweis: Ersetzen Sie http://your_sse_host durch Ihre tatsächliche SSE-Hostadresse und port durch die spezifische Portnummer, die Sie verwenden.

  2. Sobald der Dienst läuft, überschreiben Sie die Datei mcp.json mit folgendem Inhalt:

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

Für den Streamable HTTP-Modus:

  1. Starten Sie den Dienst:

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

  2. Aktualisieren Sie mcp.json:

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

Abschluss der Integration

Nachdem Sie die obigen Schritte ausgeführt haben, starten Sie Cursor neu oder laden Sie das Fenster neu, um sicherzustellen, dass die Konfiguration wirksam wird.

Überprüfung der Integration

Um zu überprüfen, ob Cursor erfolgreich mit Ihrem Milvus MCP-Server integriert wurde:

  1. Öffnen Sie Cursor Settings > MCP
  2. Prüfen Sie, ob "milvus", "milvus-sse" oder "milvus-streamable-http" in der Liste erscheinen (abhängig vom gewählten Modus)
  3. Bestätigen Sie, dass die relevanten Werkzeuge aufgelistet sind (z. B. milvus_list_collections, milvus_vector_search usw.)
  4. Wenn der Server aktiviert ist, aber einen Fehler anzeigt, lesen Sie den Abschnitt Fehlerbehebung unten

Verfügbare Werkzeuge

Der Server bietet die folgenden Werkzeuge:

Such- und Abfrageoperationen

  • milvus_text_search: Suche nach Dokumenten mittels Volltextsuche

    • Parameter:
      • collection_name: Name der zu durchsuchenden Sammlung
      • query_text: Zu suchender Text
      • limit: Maximale Anzahl der zurückzugebenden Ergebnisse (Standard: 5)
      • output_fields: In den Ergebnissen einzuschließende Felder
      • drop_ratio: Anteil der zu ignorierenden niederfrequenten Terme (0,0-1,0) (Standard: 0,2)

  • milvus_vector_search: Vektorähnlichkeitssuche in einer Sammlung durchführen

    • Parameter:
      • collection_name: Name der zu durchsuchenden Sammlung
      • vector: Abfragevektor
      • vector_field: Feldname für die Vektorsuche (Standard: "vector")
      • limit: Maximale Anzahl der zurückzugebenden Ergebnisse (Standard: 5)
      • output_fields: In den Ergebnissen einzuschließende Felder
      • filter_expr: Filterausdruck
      • metric_type: Distanzmetrik (COSINE, L2, IP) (Standard: "COSINE")
      • radius: Optionale Untergrenze für die Bereichssuche (Standard: None)
      • range_filter: Optionale Obergrenze für die Bereichssuche (Standard: None)

  • milvus_hybrid_search: Hybride Suche in einer Sammlung durchführen

    • Parameter:
      • collection_name: Name der zu durchsuchenden Sammlung
      • query_text: Textabfrage für die Suche
      • text_field: Feldname für die Textsuche
      • vector: Vektor der Textabfrage
      • vector_field: Feldname für die Vektorsuche
      • limit: Maximale Anzahl der zurückzugebenden Ergebnisse (Standard: 5)
      • output_fields: In den Ergebnissen einzuschließende Felder
      • filter_expr: Filterausdruck
      • sparse_radius: Optionale Untergrenze für die sparse Bereichssuche (Standard: None)
      • sparse_range_filter: Optionale Obergrenze für die sparse Bereichssuche (Standard: None)
      • dense_radius: Optionale Untergrenze für die dense Bereichssuche (Standard: None)
      • dense_range_filter: Optionale Obergrenze für die dense Bereichssuche (Standard: None)

  • milvus_text_similarity_search: Textähnlichkeitssuche in einer Sammlung durchführen

    Hinweis: Dieses Werkzeug wird nur in Milvus 2.6.0 und höher unterstützt. Und Sie müssen die Embedding-Funktion auf dem Milvus-Server einrichten. Siehe Embedding Function für weitere Details.

    • Parameter:
      • collection_name: Name der zu durchsuchenden Sammlung
      • query_text: Textabfrage für die Ähnlichkeitssuche
      • anns_field: Feldname für die Textsuche
      • limit: Maximale Anzahl der zurückzugebenden Ergebnisse (Standard: 5)
      • output_fields: In den Ergebnissen einzuschließende Felder
      • metric_type: Distanzmetrik (COSINE, L2, IP) (Standard: "COSINE")
      • filter_expr: Optionaler Filterausdruck
      • radius: Optionale Untergrenze für die Bereichssuche (Standard: None)
      • range_filter: Optionale Obergrenze für die Bereichssuche (Standard: None)

  • milvus_query: Sammlung mit Filterausdrücken abfragen

    • Parameter:
      • collection_name: Name der abzufragenden Sammlung
      • filter_expr: Filterausdruck (z. B. 'age > 20')
      • output_fields: In den Ergebnissen einzuschließende Felder
      • limit: Maximale Anzahl der zurückzugebenden Ergebnisse (Standard: 10)

Sammlungsverwaltung

  • milvus_list_collections: Alle Sammlungen in der Datenbank auflisten

  • milvus_create_collection: Eine neue Sammlung mit Schnelleinrichtung oder benutzerdefiniertem Schema erstellen

    • Parameter:
      • collection_name: Name für die neue Sammlung
      • auto_id: ob die ID automatisch generiert werden soll, Standard ist True
      • dimension: Vektordimension, Standard ist 768; für die Schnelleinrichtung und wird ignoriert, wenn field_schema angegeben ist
      • primary_field_name: Name des Primärfeldes, Standard ist "id"; für die Schnelleinrichtung und wird ignoriert, wenn field_schema angegeben ist
      • vector_field_name: Name des Vektorfeldes, Standard ist "vector"; für die Schnelleinrichtung und wird ignoriert, wenn field_schema angegeben ist
      • metric_type: Metriktyp, Standard ist "COSINE"; für die Schnelleinrichtung und wird ignoriert, wenn field_schema angegeben ist
      • field_schema: Liste der Feldschemata, jedes Element ist ein Dictionary mit den folgenden Schlüsseln:
        • name: Name des Feldes
        • type: Typ des Feldes
      • index_params: Optionale Liste von Indexparametern, jedes Element ist ein Dictionary mit den folgenden Schlüsseln:
        • field_name: Name des zu indizierenden Feldes
        • index_type: Indextyp
        • **kwargs: andere optionale Indexparameter
      • other_kwargs: Zusätzliche Schlüsselwortargumente für die Sammlungserstellung

  • milvus_load_collection: Eine Sammlung für Suche und Abfrage in den Speicher laden

    • Parameter:
      • collection_name: Name der zu ladenden Sammlung
      • replica_number: Anzahl der Replikate (Standard: 1)

  • milvus_release_collection: Eine Sammlung aus dem Speicher entladen

    • Parameter:
      • collection_name: Name der zu entladenden Sammlung

  • milvus_get_collection_info: Listet detaillierte Informationen wie Schema, Eigenschaften, Sammlungs-ID und andere Metadaten einer bestimmten Sammlung auf.

    • Parameter:
      • collection_name: Name der Sammlung, über die detaillierte Informationen abgerufen werden sollen

Datenoperationen

  • milvus_insert_data: Daten in eine Sammlung einfügen

    • Parameter:
      • collection_name: Name der Sammlung
      • data: Dictionary, das Feldnamen auf Wertelisten abbildet

  • milvus_delete_entities: Entitäten basierend auf einem Filterausdruck aus einer Sammlung löschen

    • Parameter:
      • collection_name: Name der Sammlung
      • filter_expr: Filterausdruck zur Auswahl der zu löschenden Entitäten

Umgebungsvariablen

  • MILVUS_URI: Milvus-Server-URI (kann anstelle von --milvus-uri gesetzt werden)
  • MILVUS_TOKEN: Optionales Authentifizierungstoken
  • MILVUS_DB: Datenbankname (Standard ist "default")

Entwicklung

Um den Server direkt auszuführen:

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

Beispiele

Claude Desktop verwenden

Beispiel 1: Sammlungen auflisten

What are the collections I have in my Milvus DB?

Claude wird dann MCP verwenden, um diese Informationen in Ihrer Milvus-DB zu überprüfen.

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

Beispiel 2: Nach Dokumenten suchen

Find documents in my text_collection that mention "machine learning"

Claude wird die Volltextsuchfunktionen von Milvus nutzen, um relevante Dokumente zu finden:

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 verwenden

Beispiel: Eine Sammlung erstellen

In Cursor können Sie fragen:

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

Cursor wird den MCP-Server verwenden, um diese Operation auszuführen:

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]

Fehlerbehebung

Häufige Probleme

Verbindungsfehler

Wenn Sie Fehler wie "Failed to connect to Milvus server" sehen:

  1. Stellen Sie sicher, dass Ihre Milvus-Instanz läuft: docker ps (bei Verwendung von Docker)
  2. Überprüfen Sie, ob die URI in Ihrer Konfiguration korrekt ist
  3. Stellen Sie sicher, dass keine Firewall-Regeln die Verbindung blockieren
  4. Versuchen Sie, 127.0.0.1 anstelle von localhost in der URI zu verwenden

Authentifizierungsprobleme

Wenn Sie Authentifizierungsfehler sehen:

  1. Überprüfen Sie, ob Ihr MILVUS_TOKEN korrekt ist
  2. Prüfen Sie, ob Ihre Milvus-Instanz eine Authentifizierung erfordert
  3. Stellen Sie sicher, dass Sie die richtigen Berechtigungen für die gewünschten Operationen haben

Tool nicht gefunden

Wenn die MCP-Tools nicht in Claude Desktop oder Cursor erscheinen:

  1. Starten Sie die Anwendung neu
  2. Überprüfen Sie die Server-Logs auf Fehler
  3. Stellen Sie sicher, dass der MCP-Server korrekt läuft
  4. Klicken Sie in den MCP-Einstellungen auf die Schaltfläche „Aktualisieren“ (bei Cursor)

Hilfe erhalten

Wenn weiterhin Probleme auftreten:

  1. Durchsuchen Sie die GitHub Issues nach ähnlichen Problemen
  2. Treten Sie dem Milvus Community Discord bei, um Unterstützung zu erhalten
  3. Erstellen Sie ein neues Issue mit detaillierten Informationen zu Ihrem Problem