Qdrant MCP

officiel

Recherche sémantique utilisant la base de données vectorielles Qdrant.

GitHub

1.5k

Que pouvez-vous faire avec Qdrant MCP ?

Stocker des informations en tant que mémoires sémantiques — Enregistrer du texte avec des métadonnées optionnelles dans une collection Qdrant à l'aide de qdrant-store.
Trouver des mémoires par leur sens — Rechercher des informations stockées avec des requêtes en langage naturel via qdrant-find.
Configurer une collection par défaut — Définir COLLECTION_NAME pour que les outils opèrent sur une collection spécifique sans avoir à la spécifier à chaque fois.
Exécuter en mode lecture seule — Désactiver l'outil de stockage en définissant QDRANT_READ_ONLY=true pour autoriser uniquement la récupération.
Personnaliser les descriptions des outils — Remplacer TOOL_STORE_DESCRIPTION et TOOL_FIND_DESCRIPTION pour réutiliser le serveur dans des workflows spécialisés comme la recherche d'extraits de code.

Documentation

mcp-server-qdrant : Un serveur MCP Qdrant

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 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 au contexte dont ils ont besoin.

Ce dépôt est un exemple de création d'un serveur MCP pour Qdrant, un moteur de recherche vectorielle.

Aperçu

Un serveur officiel Model Context Protocol pour conserver et récupérer des souvenirs dans le moteur de recherche vectorielle Qdrant. Il agit comme une couche de mémoire sémantique au-dessus de la base de données Qdrant.

Composants

Outils

qdrant-store
- Stocker des informations dans la base de données Qdrant
- Entrée :
  - information (chaîne) : Information à stocker
  - metadata (JSON) : Métadonnées facultatives à stocker
  - collection_name (chaîne) : Nom de la collection où stocker l'information. Ce champ est obligatoire s'il n'y a pas de nom de collection par défaut. S'il existe un nom de collection par défaut, ce champ n'est pas activé.
- Renvoie : Message de confirmation
qdrant-find
- Récupérer des informations pertinentes depuis la base de données Qdrant
- Entrée :
  - query (chaîne) : Requête à utiliser pour la recherche
  - collection_name (chaîne) : Nom de la collection où stocker l'information. Ce champ est obligatoire s'il n'y a pas de nom de collection par défaut. S'il existe un nom de collection par défaut, ce champ n'est pas activé.
- Renvoie : Informations stockées dans la base de données Qdrant sous forme de messages séparés

Variables d'environnement

La configuration se fait via des variables d'environnement. Le seul argument de ligne de commande est --transport, utilisé pour sélectionner le protocole de transport.

[!NOTE] Vous ne pouvez pas fournir à la fois QDRANT_URL et QDRANT_LOCAL_PATH en même temps.

Nom	Description	Valeur par défaut
`QDRANT_URL`	URL du serveur Qdrant	Aucune
`QDRANT_API_KEY`	Clé API pour le serveur Qdrant	Aucune
`COLLECTION_NAME`	Nom de la collection par défaut à utiliser.	Aucune
`QDRANT_LOCAL_PATH`	Chemin vers la base de données Qdrant locale (alternative à `QDRANT_URL`)	Aucune
`EMBEDDING_PROVIDER`	Fournisseur d'embedding à utiliser (actuellement seul "fastembed" est pris en charge)	`fastembed`
`EMBEDDING_MODEL`	Nom du modèle d'embedding à utiliser	`sentence-transformers/all-MiniLM-L6-v2`
`TOOL_STORE_DESCRIPTION`	Description personnalisée pour l'outil de stockage	Voir la valeur par défaut dans `settings.py`
`TOOL_FIND_DESCRIPTION`	Description personnalisée pour l'outil de recherche	Voir la valeur par défaut dans `settings.py`
`QDRANT_SEARCH_LIMIT`	Nombre maximum de résultats à renvoyer par la recherche	`10`
`QDRANT_READ_ONLY`	Activer le mode lecture seule (désactive l'outil `qdrant-store`)	`false`

Variables d'environnement FastMCP

Étant donné que mcp-server-qdrant est basé sur FastMCP, il prend également en charge toutes les variables d'environnement FastMCP. Les plus importantes sont listées ci-dessous :

Variable d'environnement	Description	Valeur par défaut
`FASTMCP_LOG_LEVEL`	Définir le niveau de journalisation (DEBUG, INFO, WARNING, ERROR, CRITICAL)	`INFO`
`FASTMCP_SERVER_DEBUG`	Activer le mode débogage	`false`
`FASTMCP_SERVER_HOST`	Adresse hôte à laquelle lier le serveur	`127.0.0.1`
`FASTMCP_SERVER_PORT`	Port sur lequel exécuter le serveur	`8000`
`FASTMCP_SERVER_ON_DUPLICATE_RESOURCES`	Comportement pour les ressources en double (warn, error, replace, ignore)	`warn`
`FASTMCP_SERVER_ON_DUPLICATE_TOOLS`	Comportement pour les outils en double (warn, error, replace, ignore)	`warn`
`FASTMCP_SERVER_ON_DUPLICATE_PROMPTS`	Comportement pour les invites en double (warn, error, replace, ignore)	`warn`
`FASTMCP_SERVER_DEPENDENCIES`	Liste des dépendances à installer dans l'environnement du serveur	`[]`

[!NOTE] Les paramètres spécifiques au serveur utilisent le préfixe FASTMCP_SERVER_. Cela peut changer dans les versions futures.

Installation

Utilisation de uvx

Lors de l'utilisation de uvx, aucune installation spécifique n'est nécessaire pour exécuter directement mcp-server-qdrant.

QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
EMBEDDING_MODEL="sentence-transformers/all-MiniLM-L6-v2" \
uvx mcp-server-qdrant

Protocoles de transport

Le serveur prend en charge différents protocoles de transport qui peuvent être spécifiés à l'aide du drapeau --transport :

QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
uvx mcp-server-qdrant --transport sse

Protocoles de transport pris en charge :

stdio (par défaut) : Transport entrée/sortie standard, ne peut être utilisé que par les clients MCP locaux
sse : Transport Server-Sent Events, parfait pour les clients distants
streamable-http : Transport HTTP streamable, parfait pour les clients distants, plus récent que SSE

Le transport par défaut est stdio s'il n'est pas spécifié.

Lorsque le transport SSE est utilisé, le serveur écoute sur le port spécifié et attend les connexions entrantes. Le port par défaut est 8000, mais il peut être modifié à l'aide de la variable d'environnement FASTMCP_SERVER_PORT.

QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
FASTMCP_SERVER_PORT=1234 \
uvx mcp-server-qdrant --transport sse

Utilisation de Docker

Un Dockerfile est disponible pour construire et exécuter le serveur MCP :

# Build the container
docker build -t mcp-server-qdrant .

# Run the container
docker run -p 8000:8000 \
  -e FASTMCP_SERVER_HOST="0.0.0.0" \
  -e QDRANT_URL="http://your-qdrant-server:6333" \
  -e QDRANT_API_KEY="your-api-key" \
  -e COLLECTION_NAME="your-collection" \
  mcp-server-qdrant

[!TIP] Veuillez noter que nous définissons FASTMCP_SERVER_HOST="0.0.0.0" pour que le serveur écoute sur toutes les interfaces réseau. Ceci est nécessaire lors de l'exécution du serveur dans un conteneur Docker.

Installation via Smithery

Pour installer Qdrant MCP Server pour Claude Desktop automatiquement via Smithery :

npx @smithery/cli install mcp-server-qdrant --client claude

Configuration manuelle de Claude Desktop

Pour utiliser ce serveur avec l'application Claude Desktop, ajoutez la configuration suivante à la section "mcpServers" de votre claude_desktop_config.json :

{
  "qdrant": {
    "command": "uvx",
    "args": ["mcp-server-qdrant"],
    "env": {
      "QDRANT_URL": "https://xyz-example.eu-central.aws.cloud.qdrant.io:6333",
      "QDRANT_API_KEY": "your_api_key",
      "COLLECTION_NAME": "your-collection-name",
      "EMBEDDING_MODEL": "sentence-transformers/all-MiniLM-L6-v2"
    }
  }
}

Pour le mode Qdrant local :

{
  "qdrant": {
    "command": "uvx",
    "args": ["mcp-server-qdrant"],
    "env": {
      "QDRANT_LOCAL_PATH": "/path/to/qdrant/database",
      "COLLECTION_NAME": "your-collection-name",
      "EMBEDDING_MODEL": "sentence-transformers/all-MiniLM-L6-v2"
    }
  }
}

Ce serveur MCP créera automatiquement une collection avec le nom spécifié si elle n'existe pas.

Par défaut, le serveur utilisera le modèle d'embedding sentence-transformers/all-MiniLM-L6-v2 pour encoder les souvenirs. Pour le moment, seuls les modèles FastEmbed sont pris en charge.

Prise en charge d'autres outils

Ce serveur MCP peut être utilisé avec n'importe quel client compatible MCP. Par exemple, vous pouvez l'utiliser avec Cursor et VS Code, qui fournissent une prise en charge intégrée du Model Context Protocol.

Utilisation avec Cursor/Windsurf

Vous pouvez configurer ce serveur MCP pour qu'il fonctionne comme un outil de recherche de code pour Cursor ou Windsurf en personnalisant les descriptions des outils :

QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="code-snippets" \
TOOL_STORE_DESCRIPTION="Store reusable code snippets for later retrieval. \
The 'information' parameter should contain a natural language description of what the code does, \
while the actual code should be included in the 'metadata' parameter as a 'code' property. \
The value of 'metadata' is a Python dictionary with strings as keys. \
Use this whenever you generate some code snippet." \
TOOL_FIND_DESCRIPTION="Search for relevant code snippets based on natural language descriptions. \
The 'query' parameter should describe what you're looking for, \
and the tool will return the most relevant code snippets. \
Use this when you need to find existing code snippets for reuse or reference." \
uvx mcp-server-qdrant --transport sse # Enable SSE transport

Dans Cursor/Windsurf, vous pouvez ensuite configurer le serveur MCP dans vos paramètres en pointant vers ce serveur en cours d'exécution en utilisant le protocole de transport SSE. La description sur la façon d'ajouter un serveur MCP à Cursor se trouve dans la documentation Cursor. Si vous exécutez Cursor/Windsurf localement, vous pouvez utiliser l'URL suivante :

http://localhost:8000/sse

[!TIP] Nous suggérons le transport SSE comme moyen privilégié pour connecter Cursor/Windsurf au serveur MCP, car il peut prendre en charge les connexions distantes. Cela facilite le partage du serveur avec votre équipe ou son utilisation dans un environnement cloud.

Cette configuration transforme le serveur MCP Qdrant en un outil de recherche de code spécialisé qui peut :

Stocker des extraits de code, de la documentation et des détails d'implémentation
Récupérer des exemples de code pertinents basés sur une recherche sémantique
Aider les développeurs à trouver des implémentations spécifiques ou des modèles d'utilisation

Vous pouvez peupler la base de données en stockant des descriptions en langage naturel d'extraits de code (dans le paramètre information) avec le code réel (dans la propriété metadata.code), puis les rechercher en utilisant des requêtes en langage naturel qui décrivent ce que vous cherchez.

[!NOTE] Les descriptions d'outils fournies ci-dessus sont des exemples et peuvent nécessiter d'être personnalisées pour votre cas d'utilisation spécifique. Envisagez d'ajuster les descriptions pour mieux correspondre au flux de travail de votre équipe et aux types spécifiques d'extraits de code que vous souhaitez stocker et récupérer.

Si vous avez installé avec succès le mcp-server-qdrant, mais que vous n'arrivez toujours pas à le faire fonctionner avec Cursor, veuillez envisager de créer les règles Cursor pour que les outils MCP soient toujours utilisés lorsque l'agent produit un nouvel extrait de code. Vous pouvez restreindre les règles pour qu'elles ne fonctionnent que pour certains types de fichiers, afin d'éviter d'utiliser le serveur MCP pour la documentation ou d'autres types de contenu.

Utilisation avec Claude Code

Vous pouvez améliorer les capacités de Claude Code en le connectant à ce serveur MCP, permettant une recherche sémantique sur votre base de code existante.

Configuration de mcp-server-qdrant

Ajoutez le serveur MCP à Claude Code :

# Add mcp-server-qdrant configured for code search
claude mcp add code-search \
-e QDRANT_URL="http://localhost:6333" \
-e COLLECTION_NAME="code-repository" \
-e EMBEDDING_MODEL="sentence-transformers/all-MiniLM-L6-v2" \
-e TOOL_STORE_DESCRIPTION="Store code snippets with descriptions. The 'information' parameter should contain a natural language description of what the code does, while the actual code should be included in the 'metadata' parameter as a 'code' property." \
-e TOOL_FIND_DESCRIPTION="Search for relevant code snippets using natural language. The 'query' parameter should describe the functionality you're looking for." \
-- uvx mcp-server-qdrant

Vérifiez que le serveur a été ajouté :
```
claude mcp list
```

Utilisation de la recherche de code sémantique dans Claude Code

Les descriptions d'outils, spécifiées dans TOOL_STORE_DESCRIPTION et TOOL_FIND_DESCRIPTION, guident Claude Code sur la façon d'utiliser le serveur MCP. Celles fournies ci-dessus sont des exemples et peuvent nécessiter d'être personnalisées pour votre cas d'utilisation spécifique. Cependant, Claude Code devrait déjà être capable de :

Utiliser l'outil qdrant-store pour stocker des extraits de code avec des descriptions.
Utiliser l'outil qdrant-find pour rechercher des extraits de code pertinents en utilisant le langage naturel.

Exécuter le serveur MCP en mode développement

Le serveur MCP peut être exécuté en mode développement en utilisant la commande mcp dev. Cela démarrera le serveur et ouvrira l'inspecteur MCP dans votre navigateur.

COLLECTION_NAME=mcp-dev fastmcp dev src/mcp_server_qdrant/server.py

Utilisation avec VS Code

Pour une installation en un clic, cliquez sur l'un des boutons d'installation ci-dessous :

Installation manuelle

Ajoutez le bloc JSON suivant à votre fichier de paramètres utilisateur (JSON) dans VS Code. Vous pouvez le faire en appuyant sur Ctrl + Shift + P et en tapant Preferences: Open User Settings (JSON).

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "qdrantUrl",
        "description": "Qdrant URL"
      },
      {
        "type": "promptString",
        "id": "qdrantApiKey",
        "description": "Qdrant API Key",
        "password": true
      },
      {
        "type": "promptString",
        "id": "collectionName",
        "description": "Collection Name"
      }
    ],
    "servers": {
      "qdrant": {
        "command": "uvx",
        "args": ["mcp-server-qdrant"],
        "env": {
          "QDRANT_URL": "${input:qdrantUrl}",
          "QDRANT_API_KEY": "${input:qdrantApiKey}",
          "COLLECTION_NAME": "${input:collectionName}"
        }
      }
    }
  }
}

Ou si vous préférez utiliser Docker, ajoutez cette configuration à la place :

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "qdrantUrl",
        "description": "Qdrant URL"
      },
      {
        "type": "promptString",
        "id": "qdrantApiKey",
        "description": "Qdrant API Key",
        "password": true
      },
      {
        "type": "promptString",
        "id": "collectionName",
        "description": "Collection Name"
      }
    ],
    "servers": {
      "qdrant": {
        "command": "docker",
        "args": [
          "run",
          "-p", "8000:8000",
          "-i",
          "--rm",
          "-e", "QDRANT_URL",
          "-e", "QDRANT_API_KEY",
          "-e", "COLLECTION_NAME",
          "mcp-server-qdrant"
        ],
        "env": {
          "QDRANT_URL": "${input:qdrantUrl}",
          "QDRANT_API_KEY": "${input:qdrantApiKey}",
          "COLLECTION_NAME": "${input:collectionName}"
        }
      }
    }
  }
}

Alternativement, vous pouvez créer un fichier .vscode/mcp.json dans votre espace de travail avec le contenu suivant :

{
  "inputs": [
    {
      "type": "promptString",
      "id": "qdrantUrl",
      "description": "Qdrant URL"
    },
    {
      "type": "promptString",
      "id": "qdrantApiKey",
      "description": "Qdrant API Key",
      "password": true
    },
    {
      "type": "promptString",
      "id": "collectionName",
      "description": "Collection Name"
    }
  ],
  "servers": {
    "qdrant": {
      "command": "uvx",
      "args": ["mcp-server-qdrant"],
      "env": {
        "QDRANT_URL": "${input:qdrantUrl}",
        "QDRANT_API_KEY": "${input:qdrantApiKey}",
        "COLLECTION_NAME": "${input:collectionName}"
      }
    }
  }
}

Pour la configuration de l'espace de travail avec Docker, utilisez ceci dans .vscode/mcp.json :

{
  "inputs": [
    {
      "type": "promptString",
      "id": "qdrantUrl",
      "description": "Qdrant URL"
    },
    {
      "type": "promptString",
      "id": "qdrantApiKey",
      "description": "Qdrant API Key",
      "password": true
    },
    {
      "type": "promptString",
      "id": "collectionName",
      "description": "Collection Name"
    }
  ],
  "servers": {
    "qdrant": {
      "command": "docker",
      "args": [
        "run",
        "-p", "8000:8000",
        "-i",
        "--rm",
        "-e", "QDRANT_URL",
        "-e", "QDRANT_API_KEY",
        "-e", "COLLECTION_NAME",
        "mcp-server-qdrant"
      ],
      "env": {
        "QDRANT_URL": "${input:qdrantUrl}",
        "QDRANT_API_KEY": "${input:qdrantApiKey}",
        "COLLECTION_NAME": "${input:collectionName}"
      }
    }
  }
}

Contribution

Si vous avez des suggestions sur la façon dont mcp-server-qdrant pourrait être amélioré, ou si vous voulez signaler un bug, ouvrez une issue ! Nous aimons toutes les contributions.

Tester `mcp-server-qdrant` localement

L'inspecteur MCP est un outil de développement pour tester et déboguer les serveurs MCP. Il exécute à la fois une interface utilisateur client (port par défaut 5173) et un serveur proxy MCP (port par défaut 3000). Ouvrez l'interface utilisateur client dans votre navigateur pour utiliser l'inspecteur.

QDRANT_URL=":memory:" COLLECTION_NAME="test" \
fastmcp dev src/mcp_server_qdrant/server.py

Une fois démarré, ouvrez votre navigateur sur http://localhost:5173 pour accéder à l'interface de l'inspecteur.

Licence

Ce serveur MCP est distribué sous licence Apache 2.0. Cela signifie que vous êtes libre d'utiliser, de modifier et de distribuer le logiciel, sous réserve des termes et conditions de la licence Apache 2.0. Pour plus de détails, veuillez consulter le fichier LICENSE dans le dépôt du projet.