Qdrant MCP
officielRecherche sémantique utilisant la base de données vectorielles Qdrant.
Que pouvez-vous faire avec Qdrant MCP ?
- Stocker des souvenirs — Demandez à votre assistant d’enregistrer des informations, avec des métadonnées facultatives, dans une collection Qdrant à l’aide de
qdrant-store. - Recherche sémantique — Récupérez les informations pertinentes enregistrées à partir d’une
queryen langage naturel avecqdrant-find. - Choisir une collection — Ciblez une
collection_namespécifique pour chaque appel, ou définissez une valeur par défaut viaCOLLECTION_NAME. - Personnaliser les descriptions des outils — Adaptez
TOOL_STORE_DESCRIPTIONetTOOL_FIND_DESCRIPTIONpour transformer le serveur en outil de recherche d’extraits de code. - Mode lecture seule — Activez
QDRANT_READ_ONLYpour désactiver le stockage et n’autoriser que la récupération. - Ajuster les résultats — Limitez le nombre de résultats de recherche avec
QDRANT_SEARCH_LIMITet choisissez un modèle d’intégration viaEMBEDDING_MODEL.
Documentation
mcp-server-qdrant : un serveur MCP Qdrant
Le Model Context Protocol (MCP) est un protocole ouvert qui permet une intégration fluide entre les applications LLM et les sources de données et outils externes. Que vous développiez un IDE alimenté par l’IA, amélioriez une interface de chat ou créiez des workflows d’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.
Présentation
Un serveur officiel Model Context Protocol permettant de conserver et de 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(string) : informations à stockermetadata(JSON) : métadonnées facultatives à stockercollection_name(string) : nom de la collection dans laquelle stocker les informations. Ce champ est obligatoire s’il n’existe aucun nom de collection par défaut. Si un nom de collection par défaut existe, 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(string) : requête à utiliser pour la recherchecollection_name(string) : nom de la collection dans laquelle stocker les informations. Ce champ est obligatoire s’il n’existe aucun nom de collection par défaut. Si un nom de collection par défaut existe, ce champ n’est pas activé.
- Renvoie : informations stockées dans la base de données Qdrant sous forme de messages distincts
Variables d’environnement
La configuration se fait au moyen de variables d’environnement. Le seul argument de ligne de commande est --transport, qui sert à sélectionner le protocole de transport.
[!NOTE] Vous ne pouvez pas fournir
QDRANT_URLetQDRANT_LOCAL_PATHen même temps.
| Nom | Description | Valeur par défaut |
|---|---|---|
QDRANT_URL | URL du serveur Qdrant | None |
QDRANT_API_KEY | Clé API du serveur Qdrant | None |
COLLECTION_NAME | Nom de la collection par défaut à utiliser. | None |
QDRANT_LOCAL_PATH | Chemin vers la base de données Qdrant locale (alternative à QDRANT_URL) | None |
EMBEDDING_PROVIDER | Fournisseur d’embeddings à utiliser (actuellement, seul « fastembed » est pris en charge) | fastembed |
EMBEDDING_MODEL | Nom du modèle d’embeddings à utiliser | sentence-transformers/all-MiniLM-L6-v2 |
TOOL_STORE_DESCRIPTION | Description personnalisée de l’outil store | Voir la valeur par défaut dans settings.py |
TOOL_FIND_DESCRIPTION | Description personnalisée de l’outil find | Voir la valeur par défaut dans settings.py |
QDRANT_SEARCH_LIMIT | Nombre maximal de résultats à renvoyer pour une recherche | 10 |
QDRANT_READ_ONLY | Activer le mode lecture seule (désactive l’outil qdrant-store) | false |
Variables d’environnement FastMCP
Comme mcp-server-qdrant repose sur FastMCP, il prend également en charge toutes les variables d’environnement FastMCP. Les plus
importantes sont répertorié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_DEBUG | Activer le mode débogage | false |
FASTMCP_HOST | Adresse hôte à laquelle lier le serveur (transports SSE et HTTP) | 127.0.0.1 |
FASTMCP_PORT | Port sur lequel exécuter le serveur (transports SSE et HTTP) | 8000 |
FASTMCP_MASK_ERROR_DETAILS | Masquer les détails des exceptions dans les messages d’erreur des outils envoyés aux clients | false |
[!NOTE] Avant la version 0.9.0, ces paramètres utilisaient le préfixe
FASTMCP_SERVER_, par exempleFASTMCP_SERVER_HOST. Les anciens nomsFASTMCP_SERVER_HOST,FASTMCP_SERVER_PORTetFASTMCP_SERVER_DEBUGfonctionnent toujours, mais sont obsolètes et seront supprimés dans une prochaine version. Si les deux noms sont définis, le nouveau prévaut.
Installation
Avec uvx
Avec uvx, aucune installation particulière 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 de l’option --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 par entrée/sortie standard, utilisable uniquement par les clients MCP locauxsse: transport Server-Sent Events, idéal pour les clients distantsstreamable-http: transport HTTP en flux continu, idéal pour les clients distants et plus récent que SSE
Le transport par défaut est stdio si aucun n’est 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_PORT.
QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
FASTMCP_PORT=1234 \
uvx mcp-server-qdrant --transport sse
Avec Docker
Un Dockerfile est disponible pour créer 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_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] Notez que nous définissons
FASTMCP_HOST="0.0.0.0"afin que le serveur écoute sur toutes les interfaces réseau. Cela est nécessaire lorsque le serveur s’exécute dans un conteneur Docker.
Installation via Smithery
Pour installer automatiquement Qdrant MCP Server pour Claude Desktop 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ée automatiquement une collection portant le nom spécifié si elle n’existe pas.
Par défaut, le serveur utilise le modèle d’embeddings 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 avec MCP. Par exemple, vous pouvez l’utiliser avec Cursor et VS Code, qui intègrent la prise en charge du Model Context Protocol.
Utilisation avec Cursor/Windsurf
Vous pouvez configurer ce serveur MCP comme 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 indiquant l’adresse de ce serveur en cours d’exécution avec le protocole de transport SSE. Vous trouverez les instructions pour ajouter un serveur MCP à Cursor dans la documentation de Cursor. Si vous exécutez Cursor/Windsurf localement, vous pouvez utiliser l’URL suivante :
http://localhost:8000/sse
[!TIP] Nous recommandons le transport SSE pour connecter Cursor/Windsurf au serveur MCP, car il prend en charge les connexions à distance. Il est ainsi facile de partager le serveur avec votre équipe ou de l’utiliser dans un environnement cloud.
Cette configuration transforme le serveur MCP Qdrant en un outil spécialisé de recherche de code 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 à l’aide de la recherche sémantique
- Aider les développeurs à trouver des implémentations ou des modèles d’utilisation spécifiques
Vous pouvez alimenter la base de données en stockant des descriptions en langage naturel d’extraits de code (dans le paramètre information)
ainsi que le code correspondant (dans la propriété metadata.code), puis effectuer des recherches à l’aide de requêtes en langage naturel
décrivant ce que vous recherchez.
[!NOTE] Les descriptions d’outils fournies ci-dessus sont des exemples et peuvent nécessiter une personnalisation selon votre cas d’utilisation. Pensez à les adapter au workflow de votre équipe et aux types d’extraits de code que vous souhaitez stocker et récupérer.
Si vous avez installé mcp-server-qdrant avec succès, mais que vous n’arrivez toujours pas à le faire fonctionner avec Cursor, pensez
à créer des règles Cursor afin que les outils MCP soient toujours utilisés lorsque
l’agent produit un nouvel extrait de code. Vous pouvez limiter les règles à 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, ce qui permet d’effectuer une recherche sémantique dans votre base de code existante.
Configuration de mcp-server-qdrant
-
Ajouter 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érifier que le serveur a été ajouté :
claude mcp list
Utilisation de la recherche sémantique de code dans Claude Code
Les descriptions des outils, définies dans TOOL_STORE_DESCRIPTION et TOOL_FIND_DESCRIPTION, indiquent à Claude Code comment utiliser
le serveur MCP. Celles fournies ci-dessus sont des exemples et peuvent nécessiter une personnalisation selon votre cas d’utilisation. Toutefois,
Claude Code devrait déjà pouvoir :
- Utiliser l’outil
qdrant-storepour stocker des extraits de code accompagnés de descriptions. - Utiliser l’outil
qdrant-findpour rechercher des extraits de code pertinents en langage naturel.
Exécuter le serveur MCP en mode développement
Le serveur MCP peut être exécuté en mode développement à l’aide de la commande mcp dev. Le serveur démarre alors et ouvre 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 au fichier User Settings (JSON) de VS Code. Pour cela, appuyez sur Ctrl + Shift + P et saisissez 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 plutôt cette configuration :
{
"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}"
}
}
}
}
}
Vous pouvez également 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 configurer 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 pour améliorer mcp-server-qdrant ou souhaitez signaler un bogue, ouvrez une issue ! Toutes les contributions sont les bienvenues.
Tester mcp-server-qdrant localement
L’inspecteur MCP est un outil de développement permettant de tester et de déboguer les serveurs MCP. Il exécute une interface client (port 5173 par défaut) et un serveur proxy MCP (port 3000 par défaut). Ouvrez l’interface client dans votre navigateur pour utiliser l’inspecteur.
QDRANT_URL=":memory:" COLLECTION_NAME="test" \
fastmcp dev src/mcp_server_qdrant/server.py
Une fois le serveur démarré, ouvrez http://localhost:5173 dans votre navigateur pour accéder à l’interface de l’inspecteur.
Licence
Ce serveur MCP est distribué sous licence Apache 2.0. Vous êtes donc libre d’utiliser, de modifier et de distribuer le logiciel, sous réserve des conditions de la licence Apache 2.0. Pour plus de détails, consultez le fichier LICENSE dans le dépôt du projet.