Qdrant MCP
oficialBúsqueda semántica utilizando la base de datos vectorial Qdrant.
¿Qué puedes hacer con Qdrant MCP?
- Guardar recuerdos — Pide a tu asistente que guarde información, con metadatos opcionales, en una colección de Qdrant usando
qdrant-store. - Búsqueda semántica — Recupera información almacenada relevante mediante una
queryen lenguaje natural conqdrant-find. - Elegir colección — Selecciona una
collection_nameespecífica en cada llamada o establece una predeterminada medianteCOLLECTION_NAME. - Personalizar las descripciones de las herramientas — Adapta
TOOL_STORE_DESCRIPTIONyTOOL_FIND_DESCRIPTIONpara convertir el servidor en una herramienta de búsqueda de fragmentos de código. - Modo de solo lectura — Activa
QDRANT_READ_ONLYpara deshabilitar el almacenamiento y permitir solo la recuperación. - Ajustar los resultados — Limita los resultados de búsqueda con
QDRANT_SEARCH_LIMITy elige un modelo de embeddings medianteEMBEDDING_MODEL.
Documentación
mcp-server-qdrant: Un servidor MCP de Qdrant
Model Context Protocol (MCP) es un protocolo abierto que permite una integración fluida entre las aplicaciones LLM y las fuentes de datos y herramientas externas. Tanto si estás creando un IDE con IA, mejorando una interfaz de chat o creando flujos de trabajo de IA personalizados, MCP ofrece una forma estandarizada de conectar los LLM con el contexto que necesitan.
Este repositorio es un ejemplo de cómo crear un servidor MCP para Qdrant, un motor de búsqueda vectorial.
Descripción general
Un servidor oficial de Model Context Protocol para guardar y recuperar recuerdos en el motor de búsqueda vectorial Qdrant. Actúa como una capa de memoria semántica sobre la base de datos Qdrant.
Componentes
Herramientas
qdrant-store- Guarda información en la base de datos Qdrant
- Entrada:
information(string): Información que se guardarámetadata(JSON): Metadatos opcionales que se guardaráncollection_name(string): Nombre de la colección en la que se guardará la información. Este campo es obligatorio si no hay un nombre de colección predeterminado. Si hay un nombre de colección predeterminado, este campo no está habilitado.
- Devuelve: Mensaje de confirmación
qdrant-find- Recupera información relevante de la base de datos Qdrant
- Entrada:
query(string): Consulta que se usará para la búsquedacollection_name(string): Nombre de la colección en la que se guardará la información. Este campo es obligatorio si no hay un nombre de colección predeterminado. Si hay un nombre de colección predeterminado, este campo no está habilitado.
- Devuelve: Información almacenada en la base de datos Qdrant como mensajes separados
Variables de entorno
La configuración se realiza mediante variables de entorno. El único argumento de línea de comandos es --transport, que se usa para seleccionar el protocolo de transporte.
[!NOTE] No puedes proporcionar
QDRANT_URLyQDRANT_LOCAL_PATHal mismo tiempo.
| Nombre | Descripción | Valor predeterminado |
|---|---|---|
QDRANT_URL | URL del servidor Qdrant | None |
QDRANT_API_KEY | Clave de API del servidor Qdrant | None |
COLLECTION_NAME | Nombre de la colección predeterminada que se usará. | None |
QDRANT_LOCAL_PATH | Ruta a la base de datos local de Qdrant (alternativa a QDRANT_URL) | None |
EMBEDDING_PROVIDER | Proveedor de embeddings que se usará (actualmente solo se admite "fastembed") | fastembed |
EMBEDDING_MODEL | Nombre del modelo de embeddings que se usará | sentence-transformers/all-MiniLM-L6-v2 |
TOOL_STORE_DESCRIPTION | Descripción personalizada para la herramienta store | Consulta el valor predeterminado en settings.py |
TOOL_FIND_DESCRIPTION | Descripción personalizada para la herramienta find | Consulta el valor predeterminado en settings.py |
QDRANT_SEARCH_LIMIT | Número máximo de resultados que se devolverán en la búsqueda | 10 |
QDRANT_READ_ONLY | Habilita el modo de solo lectura (deshabilita la herramienta qdrant-store) | false |
Variables de entorno de FastMCP
Como mcp-server-qdrant se basa en FastMCP, también admite todas las variables de entorno de FastMCP. A continuación se
enumeran las más importantes:
| Variable de entorno | Descripción | Valor predeterminado |
|---|---|---|
FASTMCP_LOG_LEVEL | Establece el nivel de registro (DEBUG, INFO, WARNING, ERROR, CRITICAL) | INFO |
FASTMCP_DEBUG | Habilita el modo de depuración | false |
FASTMCP_HOST | Dirección del host a la que se enlazará el servidor (transportes SSE y HTTP) | 127.0.0.1 |
FASTMCP_PORT | Puerto en el que se ejecutará el servidor (transportes SSE y HTTP) | 8000 |
FASTMCP_MASK_ERROR_DETAILS | Oculta los detalles de las excepciones en los mensajes de error de las herramientas enviados a los clientes | false |
[!NOTE] Antes de la versión 0.9.0, estos ajustes usaban el prefijo
FASTMCP_SERVER_, por ejemplo,FASTMCP_SERVER_HOST. Los nombres antiguosFASTMCP_SERVER_HOST,FASTMCP_SERVER_PORTyFASTMCP_SERVER_DEBUGsiguen funcionando, pero están obsoletos y se eliminarán en una versión futura. Si se establecen ambos nombres, prevalece el nuevo.
Instalación
Uso de uvx
Al usar uvx, no se necesita ninguna instalación específica para ejecutar directamente mcp-server-qdrant.
QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
EMBEDDING_MODEL="sentence-transformers/all-MiniLM-L6-v2" \
uvx mcp-server-qdrant
Protocolos de transporte
El servidor admite distintos protocolos de transporte que se pueden especificar mediante la opción --transport:
QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
uvx mcp-server-qdrant --transport sse
Protocolos de transporte admitidos:
stdio(predeterminado): Transporte de entrada/salida estándar; quizá solo puedan usarlo los clientes MCP localessse: Transporte de eventos enviados por el servidor, ideal para clientes remotosstreamable-http: Transporte HTTP con capacidad de transmisión, ideal para clientes remotos y más reciente que SSE
Si no se especifica, el transporte predeterminado es stdio.
Cuando se usa el transporte SSE, el servidor escucha en el puerto especificado y espera conexiones entrantes. El puerto predeterminado
es 8000, pero se puede cambiar mediante la variable de entorno FASTMCP_PORT.
QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
FASTMCP_PORT=1234 \
uvx mcp-server-qdrant --transport sse
Uso de Docker
Hay un Dockerfile disponible para compilar y ejecutar el servidor 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] Ten en cuenta que establecemos
FASTMCP_HOST="0.0.0.0"para que el servidor escuche en todas las interfaces de red. Esto es necesario al ejecutar el servidor en un contenedor Docker.
Instalación mediante Smithery
Para instalar automáticamente Qdrant MCP Server para Claude Desktop mediante Smithery:
npx @smithery/cli install mcp-server-qdrant --client claude
Configuración manual de Claude Desktop
Para usar este servidor con la aplicación Claude Desktop, añade la siguiente configuración a la sección "mcpServers" de tu
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"
}
}
}
Para el modo 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"
}
}
}
Este servidor MCP creará automáticamente una colección con el nombre especificado si aún no existe.
De forma predeterminada, el servidor usará el modelo de embeddings sentence-transformers/all-MiniLM-L6-v2 para codificar los recuerdos.
Por el momento, solo se admiten modelos de FastEmbed.
Compatibilidad con otras herramientas
Este servidor MCP se puede usar con cualquier cliente compatible con MCP. Por ejemplo, puedes usarlo con Cursor y VS Code, que ofrecen compatibilidad integrada con Model Context Protocol.
Uso con Cursor/Windsurf
Puedes configurar este servidor MCP para que funcione como herramienta de búsqueda de código en Cursor o Windsurf personalizando las descripciones de las herramientas:
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
A continuación, en Cursor/Windsurf, puedes configurar el servidor MCP en los ajustes indicando este servidor en ejecución mediante el protocolo de transporte SSE. Puedes encontrar instrucciones para añadir un servidor MCP a Cursor en la documentación de Cursor. Si ejecutas Cursor/Windsurf localmente, puedes usar la siguiente URL:
http://localhost:8000/sse
[!TIP] Recomendamos el transporte SSE como forma preferida de conectar Cursor/Windsurf al servidor MCP, ya que permite conexiones remotas. Esto facilita compartir el servidor con tu equipo o usarlo en un entorno en la nube.
Esta configuración convierte el servidor MCP de Qdrant en una herramienta especializada de búsqueda de código que puede:
- Almacenar fragmentos de código, documentación y detalles de implementación
- Recuperar ejemplos de código relevantes mediante búsqueda semántica
- Ayudar a los desarrolladores a encontrar implementaciones o patrones de uso específicos
Puedes llenar la base de datos almacenando descripciones en lenguaje natural de fragmentos de código (en el parámetro information)
junto con el código correspondiente (en la propiedad metadata.code) y, después, buscarlos mediante consultas en lenguaje natural
que describan lo que buscas.
[!NOTE] Las descripciones de las herramientas proporcionadas arriba son ejemplos y quizá deban personalizarse para tu caso de uso específico. Considera ajustarlas para que se adapten mejor al flujo de trabajo de tu equipo y a los tipos específicos de fragmentos de código que quieres almacenar y recuperar.
Si has instalado correctamente mcp-server-qdrant, pero aún no consigues que funcione con Cursor, considera crear las reglas de Cursor para que las herramientas MCP se usen siempre cuando
el agente genere un nuevo fragmento de código. Puedes limitar las reglas para que solo se apliquen a ciertos tipos de archivo y así evitar que se use
el servidor MCP con la documentación u otros tipos de contenido.
Uso con Claude Code
Puedes ampliar las capacidades de Claude Code conectándolo a este servidor MCP, lo que permite realizar búsquedas semánticas en tu base de código existente.
Configuración de mcp-server-qdrant
-
Añade el servidor MCP a 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 -
Verifica que se haya añadido el servidor:
claude mcp list
Uso de la búsqueda semántica de código en Claude Code
Las descripciones de las herramientas, especificadas en TOOL_STORE_DESCRIPTION y TOOL_FIND_DESCRIPTION, indican a Claude Code cómo usar
el servidor MCP. Las proporcionadas arriba son ejemplos y quizá deban personalizarse para tu caso de uso específico. Sin embargo,
Claude Code ya debería poder:
- Usar la herramienta
qdrant-storepara almacenar fragmentos de código con descripciones. - Usar la herramienta
qdrant-findpara buscar fragmentos de código relevantes mediante lenguaje natural.
Ejecutar el servidor MCP en modo de desarrollo
El servidor MCP se puede ejecutar en modo de desarrollo mediante el comando mcp dev. Esto iniciará el servidor y abrirá el inspector MCP
en el navegador.
COLLECTION_NAME=mcp-dev fastmcp dev src/mcp_server_qdrant/server.py
Uso con VS Code
Para instalarlo con un solo clic, haz clic en uno de los botones de instalación siguientes:
Instalación manual
Añade el siguiente bloque JSON al archivo User Settings (JSON) de VS Code. Puedes hacerlo pulsando Ctrl + Shift + P y escribiendo 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}"
}
}
}
}
}
O, si prefieres usar Docker, añade esta configuración:
{
"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}"
}
}
}
}
}
También puedes crear un archivo .vscode/mcp.json en tu espacio de trabajo con el siguiente contenido:
{
"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}"
}
}
}
}
Para configurar el espacio de trabajo con Docker, usa esto en .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}"
}
}
}
}
Contribuciones
Si tienes sugerencias para mejorar mcp-server-qdrant o quieres informar de un error, ¡abre una incidencia! Nos encantan todas las contribuciones.
Probar mcp-server-qdrant localmente
El inspector MCP es una herramienta para desarrolladores que permite probar y depurar servidores MCP. Ejecuta tanto una interfaz de cliente (puerto predeterminado 5173) como un servidor proxy MCP (puerto predeterminado 3000). Abre la interfaz de cliente en el navegador para usar el inspector.
QDRANT_URL=":memory:" COLLECTION_NAME="test" \
fastmcp dev src/mcp_server_qdrant/server.py
Una vez iniciado, abre http://localhost:5173 en el navegador para acceder a la interfaz del inspector.
Licencia
Este servidor MCP está sujeto a la licencia Apache License 2.0. Esto significa que puedes usar, modificar y distribuir el software, de acuerdo con los términos y condiciones de Apache License 2.0. Para obtener más información, consulta el archivo LICENSE del repositorio del proyecto.