Qdrant MCP

oficial

Bú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 query en lenguaje natural con qdrant-find.
  • Elegir colección — Selecciona una collection_name específica en cada llamada o establece una predeterminada mediante COLLECTION_NAME.
  • Personalizar las descripciones de las herramientas — Adapta TOOL_STORE_DESCRIPTION y TOOL_FIND_DESCRIPTION para convertir el servidor en una herramienta de búsqueda de fragmentos de código.
  • Modo de solo lectura — Activa QDRANT_READ_ONLY para deshabilitar el almacenamiento y permitir solo la recuperación.
  • Ajustar los resultados — Limita los resultados de búsqueda con QDRANT_SEARCH_LIMIT y elige un modelo de embeddings mediante EMBEDDING_MODEL.

Documentación

mcp-server-qdrant: Un servidor MCP de Qdrant

smithery badge

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

  1. 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án
      • collection_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
  2. qdrant-find
    • Recupera información relevante de la base de datos Qdrant
    • Entrada:
      • query (string): Consulta que se usará para la búsqueda
      • collection_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_URL y QDRANT_LOCAL_PATH al mismo tiempo.

NombreDescripciónValor predeterminado
QDRANT_URLURL del servidor QdrantNone
QDRANT_API_KEYClave de API del servidor QdrantNone
COLLECTION_NAMENombre de la colección predeterminada que se usará.None
QDRANT_LOCAL_PATHRuta a la base de datos local de Qdrant (alternativa a QDRANT_URL)None
EMBEDDING_PROVIDERProveedor de embeddings que se usará (actualmente solo se admite "fastembed")fastembed
EMBEDDING_MODELNombre del modelo de embeddings que se usarásentence-transformers/all-MiniLM-L6-v2
TOOL_STORE_DESCRIPTIONDescripción personalizada para la herramienta storeConsulta el valor predeterminado en settings.py
TOOL_FIND_DESCRIPTIONDescripción personalizada para la herramienta findConsulta el valor predeterminado en settings.py
QDRANT_SEARCH_LIMITNúmero máximo de resultados que se devolverán en la búsqueda10
QDRANT_READ_ONLYHabilita 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 entornoDescripciónValor predeterminado
FASTMCP_LOG_LEVELEstablece el nivel de registro (DEBUG, INFO, WARNING, ERROR, CRITICAL)INFO
FASTMCP_DEBUGHabilita el modo de depuraciónfalse
FASTMCP_HOSTDirección del host a la que se enlazará el servidor (transportes SSE y HTTP)127.0.0.1
FASTMCP_PORTPuerto en el que se ejecutará el servidor (transportes SSE y HTTP)8000
FASTMCP_MASK_ERROR_DETAILSOculta los detalles de las excepciones en los mensajes de error de las herramientas enviados a los clientesfalse

[!NOTE] Antes de la versión 0.9.0, estos ajustes usaban el prefijo FASTMCP_SERVER_, por ejemplo, FASTMCP_SERVER_HOST. Los nombres antiguos FASTMCP_SERVER_HOST, FASTMCP_SERVER_PORT y FASTMCP_SERVER_DEBUG siguen 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 locales
  • sse: Transporte de eventos enviados por el servidor, ideal para clientes remotos
  • streamable-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:

  1. Almacenar fragmentos de código, documentación y detalles de implementación
  2. Recuperar ejemplos de código relevantes mediante búsqueda semántica
  3. 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

  1. 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
    
  2. 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:

  1. Usar la herramienta qdrant-store para almacenar fragmentos de código con descripciones.
  2. Usar la herramienta qdrant-find para 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:

Install with UVX in VS Code Install with UVX in VS Code Insiders

Install with Docker in VS Code Install with Docker in VS Code Insiders

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.

Privacidad y asistencia