Milvus MCP Server

officiel

Recherchez, interrogez et interagissez avec les données de votre base vectorielle Milvus.

GitHub
233

Documentation

Serveur MCP pour Milvus

Le Model Context Protocol (MCP) est un protocole ouvert qui permet une intégration transparente entre les applications LLM et les sources de données et outils externes. Que vous construisiez un IDE alimenté par l'IA, amélioriez une interface de chat ou créiez des flux de travail IA personnalisés, MCP fournit un moyen standardisé de connecter les LLM avec le contexte dont ils ont besoin.

Ce dépôt contient un serveur MCP qui donne accès aux fonctionnalités de la base de données vectorielle Milvus.

MCP with Milvus

Prérequis

Avant d'utiliser ce serveur MCP, assurez-vous d'avoir :

  • Python 3.10 ou supérieur
  • Une instance Milvus en cours d'exécution (locale ou distante)
  • uv installé (recommandé pour exécuter le serveur)

Utilisation

La méthode recommandée pour utiliser ce serveur MCP est de l'exécuter directement avec uv sans installation. C'est ainsi que Claude Desktop et Cursor sont configurés pour l'utiliser dans les exemples ci-dessous.

Si vous souhaitez cloner le dépôt :

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

Ensuite, vous pouvez exécuter le serveur directement :

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

Vous pouvez également modifier le fichier .env dans le répertoire src/mcp_server_milvus/ pour définir les variables d'environnement et exécuter le serveur avec la commande suivante :

uv run src/mcp_server_milvus/server.py

Important : le fichier .env aura une priorité plus élevée que les arguments de ligne de commande.

Modes d'exécution

Le serveur prend en charge deux modes d'exécution : stdio (par défaut) et SSE (Server-Sent Events).

Mode Stdio (par défaut)

  • Description : Communique avec le client via l'entrée/sortie standard. C'est le mode par défaut si aucun mode n'est spécifié.

  • Utilisation :

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

Mode SSE

  • Description : Utilise les Server-Sent Events HTTP pour la communication. Ce mode permet à plusieurs clients de se connecter via HTTP et convient aux applications web.

  • Utilisation :

    uv run src/mcp_server_milvus/server.py --sse --milvus-uri http://localhost:19530 --port 8000
    • --sse : Active le mode SSE.
    • --port : Spécifie le port pour le serveur SSE (par défaut : 8000).

  • Débogage en mode SSE :

    Si vous souhaitez déboguer en mode SSE, après avoir démarré le service SSE, entrez la commande suivante :

    mcp dev src/mcp_server_milvus/server.py

    La sortie sera similaire à :

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

    Vous pouvez ensuite accéder à l'inspecteur MCP à l'adresse http://127.0.0.1:6274 pour les tests.

Mode HTTP Streamable

  • Description : Utilise HTTP avec prise en charge du streaming pour la communication. C'est le transport recommandé pour les déploiements en production et prend en charge le fonctionnement avec et sans état.

  • Utilisation :

    uv run src/mcp_server_milvus/server.py --streamable-http --milvus-uri http://localhost:19530 --port 8000
    • --streamable-http : Active le mode HTTP Streamable.
    • --port : Spécifie le port du serveur (par défaut : 8000).
    • --stateless : Drapeau optionnel pour le mode sans état (pas de persistance de session).

  • Mode sans état :

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

Applications prises en charge

Ce serveur MCP peut être utilisé avec diverses applications LLM qui prennent en charge le Model Context Protocol :

  • Claude Desktop : L'application de bureau d'Anthropic pour Claude
  • Cursor : Éditeur de code alimenté par l'IA avec prise en charge MCP
  • Clients MCP personnalisés : Toute application implémentant la spécification du client MCP

Utilisation avec Claude Desktop

Configuration pour différents modes

Configuration du mode SSE

Suivez ces étapes pour configurer Claude Desktop pour le mode SSE :

  1. Installez Claude Desktop depuis https://claude.ai/download.
  2. Ouvrez votre fichier de configuration Claude Desktop :
    • macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
  3. Ajoutez la configuration suivante pour le mode SSE :
{
  "mcpServers": {
    "milvus-sse": {
      "url": "http://your_sse_host:port/sse",
      "disabled": false,
      "autoApprove": []
    }
  }
}

Configuration du mode HTTP Streamable

{
  "mcpServers": {
    "milvus-streamable-http": {
      "url": "http://your_host:port/mcp",
      "disabled": false,
      "autoApprove": []
    }
  }
}
  1. Redémarrez Claude Desktop pour appliquer les modifications.

Configuration du mode Stdio

Pour le mode stdio, suivez ces étapes :

  1. Installez Claude Desktop depuis https://claude.ai/download.
  2. Ouvrez votre fichier de configuration Claude Desktop :
    • macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
  3. Ajoutez la configuration suivante pour le 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. Redémarrez Claude Desktop pour appliquer les modifications.

Utilisation avec Cursor

Cursor prend également en charge les outils MCP. Vous pouvez intégrer votre serveur MCP Milvus avec Cursor en suivant ces étapes :

Étapes d'intégration

  1. Ouvrez Cursor Settings > MCP
  2. Cliquez sur Add new global MCP server
  3. Après avoir cliqué, vous serez automatiquement redirigé vers le fichier mcp.json, qui sera créé s'il n'existe pas

Configuration du fichier mcp.json

Pour le mode Stdio :

Écrasez le fichier mcp.json avec le contenu suivant :

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

Pour le mode SSE :

  1. Démarrez le service en exécutant la commande suivante :

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

    Remarque : Remplacez http://your_sse_host par votre adresse d'hôte SSE réelle et port par le numéro de port spécifique que vous utilisez.

  2. Une fois le service opérationnel, écrasez le fichier mcp.json avec le contenu suivant :

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

Pour le mode HTTP Streamable :

  1. Démarrez le service :

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

  2. Mettez à jour mcp.json :

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

Finalisation de l'intégration

Après avoir terminé les étapes ci-dessus, redémarrez Cursor ou rechargez la fenêtre pour vous assurer que la configuration prend effet.

Vérification de l'intégration

Pour vérifier que Cursor s'est intégré avec succès à votre serveur MCP Milvus :

  1. Ouvrez Cursor Settings > MCP
  2. Vérifiez si "milvus", "milvus-sse" ou "milvus-streamable-http" apparaissent dans la liste (selon le mode que vous avez choisi)
  3. Confirmez que les outils pertinents sont listés (par exemple, milvus_list_collections, milvus_vector_search, etc.)
  4. Si le serveur est activé mais affiche une erreur, consultez la section Dépannage ci-dessous

Outils disponibles

Le serveur fournit les outils suivants :

Opérations de recherche et de requête

  • milvus_text_search : Rechercher des documents en utilisant la recherche en texte intégral

    • Paramètres :
      • collection_name : Nom de la collection à rechercher
      • query_text : Texte à rechercher
      • limit : Le nombre maximum de résultats à retourner (par défaut : 5)
      • output_fields : Champs à inclure dans les résultats
      • drop_ratio : Proportion de termes à basse fréquence à ignorer (0.0-1.0) (par défaut : 0.2)

  • milvus_vector_search : Effectuer une recherche de similarité vectorielle sur une collection

    • Paramètres :
      • collection_name : Nom de la collection à rechercher
      • vector : Vecteur de requête
      • vector_field : Nom du champ pour la recherche vectorielle (par défaut : "vector")
      • limit : Le nombre maximum de résultats à retourner (par défaut : 5)
      • output_fields : Champs à inclure dans les résultats
      • filter_expr : Expression de filtre
      • metric_type : Métrique de distance (COSINE, L2, IP) (par défaut : "COSINE")
      • radius : Borne inférieure optionnelle pour la recherche par plage (par défaut : None)
      • range_filter : Borne supérieure optionnelle pour la recherche par plage (par défaut : None)

  • milvus_hybrid_search : Effectuer une recherche hybride sur une collection

    • Paramètres :
      • collection_name : Nom de la collection à rechercher
      • query_text : Requête textuelle pour la recherche
      • text_field : Nom du champ pour la recherche textuelle
      • vector : Vecteur de la requête textuelle
      • vector_field : Nom du champ pour la recherche vectorielle
      • limit : Le nombre maximum de résultats à retourner (par défaut : 5)
      • output_fields : Champs à inclure dans les résultats
      • filter_expr : Expression de filtre
      • sparse_radius : Borne inférieure optionnelle pour la recherche par plage sparse (par défaut : None)
      • sparse_range_filter : Borne supérieure optionnelle pour la recherche par plage sparse (par défaut : None)
      • dense_radius : Borne inférieure optionnelle pour la recherche par plage dense (par défaut : None)
      • dense_range_filter : Borne supérieure optionnelle pour la recherche par plage dense (par défaut : None)

  • milvus_text_similarity_search : Effectuer une recherche de similarité textuelle sur une collection

    Remarque : Cet outil n'est pris en charge que dans Milvus 2.6.0 et supérieur. Et vous devez définir la fonction d'embedding sur le serveur Milvus. Voir Fonction d'embedding pour plus de détails.

    • Paramètres :
      • collection_name : Nom de la collection à rechercher
      • query_text : Requête textuelle pour la recherche de similarité
      • anns_field : Nom du champ pour la recherche textuelle
      • limit : Le nombre maximum de résultats à retourner (par défaut : 5)
      • output_fields : Champs à inclure dans les résultats
      • metric_type : Métrique de distance (COSINE, L2, IP) (par défaut : "COSINE")
      • filter_expr : Expression de filtre optionnelle
      • radius : Borne inférieure optionnelle pour la recherche par plage (par défaut : None)
      • range_filter : Borne supérieure optionnelle pour la recherche par plage (par défaut : None)

  • milvus_query : Interroger une collection en utilisant des expressions de filtre

    • Paramètres :
      • collection_name : Nom de la collection à interroger
      • filter_expr : Expression de filtre (par exemple 'age > 20')
      • output_fields : Champs à inclure dans les résultats
      • limit : Le nombre maximum de résultats à retourner (par défaut : 10)

Gestion des collections

  • milvus_list_collections : Lister toutes les collections dans la base de données

  • milvus_create_collection : Créer une nouvelle collection avec une configuration rapide ou un schéma personnalisé

    • Paramètres :
      • collection_name : Nom de la nouvelle collection
      • auto_id : s'il faut générer automatiquement l'ID, par défaut True
      • dimension : dimension du vecteur, par défaut 768 ; pour la configuration rapide et sera ignoré si field_schema est fourni
      • primary_field_name : nom du champ primaire, par défaut "id" ; pour la configuration rapide et sera ignoré si field_schema est fourni
      • vector_field_name : nom du champ vectoriel, par défaut "vector" ; pour la configuration rapide et sera ignoré si field_schema est fourni
      • metric_type : type de métrique, par défaut "COSINE" ; pour la configuration rapide et sera ignoré si field_schema est fourni
      • field_schema : Liste des schémas de champ, chaque élément est un dictionnaire avec les clés suivantes :
        • name : nom du champ
        • type : type du champ
      • index_params : Liste optionnelle des paramètres d'index, chaque élément est un dictionnaire avec les clés suivantes :
        • field_name : nom du champ à indexer
        • index_type : type d'index
        • **kwargs : autres paramètres d'index optionnels
      • other_kwargs : Arguments nommés supplémentaires pour la création de la collection

  • milvus_load_collection : Charger une collection en mémoire pour la recherche et la requête

    • Paramètres :
      • collection_name : Nom de la collection à charger
      • replica_number : Nombre de réplicas (par défaut : 1)

  • milvus_release_collection : Libérer une collection de la mémoire

    • Paramètres :
      • collection_name : Nom de la collection à libérer

  • milvus_get_collection_info : Liste des informations détaillées comme le schéma, les propriétés, l'ID de collection et d'autres métadonnées d'une collection spécifique.

    • Paramètres :
      • collection_name : Nom de la collection pour laquelle obtenir des informations détaillées

Opérations sur les données

  • milvus_insert_data : Insérer des données dans une collection

    • Paramètres :
      • collection_name : Nom de la collection
      • data : Dictionnaire mappant les noms de champ aux listes de valeurs

  • milvus_delete_entities : Supprimer des entités d'une collection en fonction d'une expression de filtre

    • Paramètres :
      • collection_name : Nom de la collection
      • filter_expr : Expression de filtre pour sélectionner les entités à supprimer

Variables d'environnement

  • MILVUS_URI : URI du serveur Milvus (peut être défini à la place de --milvus-uri)
  • MILVUS_TOKEN : Jeton d'authentification optionnel
  • MILVUS_DB : Nom de la base de données (par défaut "default")

Développement

Pour exécuter le serveur directement :

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

Exemples

Utilisation de Claude Desktop

Exemple 1 : Lister les collections

What are the collections I have in my Milvus DB?

Claude utilisera alors MCP pour vérifier ces informations sur votre base de données Milvus.

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

Exemple 2 : Rechercher des documents

Find documents in my text_collection that mention "machine learning"

Claude utilisera les capacités de recherche en texte intégral de Milvus pour trouver des documents pertinents :

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]

Utilisation de Cursor

Exemple : Créer une collection

Dans Cursor, vous pouvez demander :

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

Cursor utilisera le serveur MCP pour exécuter cette opération :

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]

Dépannage

Problèmes courants

Erreurs de connexion

Si vous voyez des erreurs comme "Échec de la connexion au serveur Milvus" :

  1. Vérifiez que votre instance Milvus est en cours d'exécution : docker ps (si vous utilisez Docker)
  2. Vérifiez que l'URI est correct dans votre configuration
  3. Assurez-vous qu'aucune règle de pare-feu ne bloque la connexion
  4. Essayez d'utiliser 127.0.0.1 au lieu de localhost dans l'URI

Problèmes d'authentification

Si vous rencontrez des erreurs d'authentification :

  1. Vérifiez que votre MILVUS_TOKEN est correct
  2. Vérifiez si votre instance Milvus nécessite une authentification
  3. Assurez-vous d'avoir les permissions appropriées pour les opérations que vous essayez d'effectuer

Outil introuvable

Si les outils MCP n'apparaissent pas dans Claude Desktop ou Cursor :

  1. Redémarrez l'application
  2. Consultez les journaux du serveur pour détecter d'éventuelles erreurs
  3. Vérifiez que le serveur MCP fonctionne correctement
  4. Appuyez sur le bouton d'actualisation dans les paramètres MCP (pour Cursor)

Obtenir de l'aide

Si vous continuez à rencontrer des problèmes :

  1. Consultez les problèmes GitHub pour des problèmes similaires
  2. Rejoignez le Discord de la communauté Milvus pour obtenir de l'aide
  3. Ouvrez un nouveau ticket avec des informations détaillées sur votre problème