Qdrant

oficial

Implementar una capa

GitHub
1.5k

¿Qué puedes hacer con Qdrant MCP?

  • Almacenar recuerdos — Pídele a tu asistente que guarde información con qdrant-store, opcionalmente incluyendo metadatos y apuntando a una colección específica.
  • Búsqueda semántica — Usa qdrant-find para recuperar información almacenada relevante mediante consultas en lenguaje natural, con resultados limitados por QDRANT_SEARCH_LIMIT.
  • Gestión de fragmentos de código — Configura las descripciones de las herramientas para almacenar código con metadatos y recuperarlo mediante búsqueda semántica para reutilizarlo en Cursor o Claude Code.
  • Modo de solo lectura — Activa QDRANT_READ_ONLY para deshabilitar qdrant-store y permitir solo operaciones de búsqueda.

Documentación

mcp-server-qdrant: Un servidor MCP de Qdrant

smithery badge

El Protocolo de Contexto de Modelos (MCP) es un protocolo abierto que permite la integración perfecta entre aplicaciones LLM y fuentes de datos y herramientas externas. Ya sea que estés construyendo un IDE impulsado por IA, mejorando una interfaz de chat o creando flujos de trabajo de IA personalizados, MCP proporciona una forma estandarizada de conectar LLMs 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 del Protocolo de Contexto de Modelos para almacenar y recuperar memorias 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
    • Almacena información en la base de datos Qdrant
    • Entrada:
      • information (cadena): Información a almacenar
      • metadata (JSON): Metadatos opcionales a almacenar
      • collection_name (cadena): Nombre de la colección donde se almacenará la información. Este campo es obligatorio si no hay un nombre de colección predeterminado. Si existe 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 (cadena): Consulta a utilizar para la búsqueda
      • collection_name (cadena): Nombre de la colección donde se almacenará la información. Este campo es obligatorio si no hay un nombre de colección predeterminado. Si existe 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, utilizado 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 QdrantNinguno
QDRANT_API_KEYClave de API para el servidor QdrantNinguno
COLLECTION_NAMENombre de la colección predeterminada a utilizar.Ninguno
QDRANT_LOCAL_PATHRuta a la base de datos local de Qdrant (alternativa a QDRANT_URL)Ninguno
EMBEDDING_PROVIDERProveedor de embeddings a utilizar (actualmente solo se admite "fastembed")fastembed
EMBEDDING_MODELNombre del modelo de embeddings a utilizarsentence-transformers/all-MiniLM-L6-v2
TOOL_STORE_DESCRIPTIONDescripción personalizada para la herramienta de almacenamientoVer predeterminado en settings.py
TOOL_FIND_DESCRIPTIONDescripción personalizada para la herramienta de búsquedaVer predeterminado en settings.py
QDRANT_SEARCH_LIMITNúmero máximo de resultados a devolver de la búsqueda10
QDRANT_READ_ONLYHabilitar modo de solo lectura (deshabilita la herramienta qdrant-store)false

Variables de entorno de FastMCP

Dado que mcp-server-qdrant se basa en FastMCP, también admite todas las variables de entorno de FastMCP. Las más importantes se enumeran a continuación:

Variable de entornoDescripciónValor predeterminado
FASTMCP_LOG_LEVELEstablecer nivel de registro (DEBUG, INFO, WARNING, ERROR, CRITICAL)INFO
FASTMCP_SERVER_DEBUGHabilitar modo de depuraciónfalse
FASTMCP_SERVER_HOSTDirección de host para vincular el servidor127.0.0.1
FASTMCP_SERVER_PORTPuerto para ejecutar el servidor8000
FASTMCP_SERVER_ON_DUPLICATE_RESOURCESComportamiento para recursos duplicados (warn, error, replace, ignore)warn
FASTMCP_SERVER_ON_DUPLICATE_TOOLSComportamiento para herramientas duplicadas (warn, error, replace, ignore)warn
FASTMCP_SERVER_ON_DUPLICATE_PROMPTSComportamiento para prompts duplicados (warn, error, replace, ignore)warn
FASTMCP_SERVER_DEPENDENCIESLista de dependencias a instalar en el entorno del servidor[]

[!NOTE] La configuración específica del servidor utiliza el prefijo FASTMCP_SERVER_. Esto puede cambiar en versiones futuras.

Instalación

Usando uvx

Cuando se usa 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 diferentes protocolos de transporte que se pueden especificar usando la bandera --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, solo puede ser utilizado por clientes MCP locales
  • sse: transporte Server-Sent Events, perfecto para clientes remotos
  • streamable-http: transporte HTTP transmisible, perfecto para clientes remotos, más reciente que SSE

El transporte predeterminado es stdio si no se especifica.

Cuando se usa el transporte SSE, el servidor escuchará en el puerto especificado y esperará conexiones entrantes. El puerto predeterminado es 8000; sin embargo, se puede cambiar usando la variable de entorno FASTMCP_SERVER_PORT.

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

Usando Docker

Hay un Dockerfile disponible para construir y ejecutar el servidor 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] Ten en cuenta que configuramos FASTMCP_SERVER_HOST="0.0.0.0" para que el servidor escuche en todas las interfaces de red. Esto es necesario cuando se ejecuta el servidor en un contenedor Docker.

Instalación mediante Smithery

Para instalar el Servidor MCP de Qdrant para Claude Desktop automáticamente 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, agrega 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 local de Qdrant:

{
  "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 no existe.

Por defecto, el servidor utilizará el modelo de embeddings sentence-transformers/all-MiniLM-L6-v2 para codificar memorias. Por el momento, solo se admiten modelos 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 proporcionan soporte integrado para el Protocolo de Contexto de Modelos.

Uso con Cursor/Windsurf

Puedes configurar este servidor MCP para que funcione como una herramienta de búsqueda de código para 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

En Cursor/Windsurf, puedes configurar el servidor MCP en tus ajustes apuntando a este servidor en ejecución usando el protocolo de transporte SSE. La descripción de cómo agregar un servidor MCP a Cursor se puede encontrar en la documentación de Cursor. Si estás ejecutando Cursor/Windsurf localmente, puedes usar la siguiente URL:

http://localhost:8000/sse

[!TIP] Sugerimos el transporte SSE como una forma preferida de conectar Cursor/Windsurf al servidor MCP, ya que puede admitir conexiones remotas. Eso facilita compartir el servidor con tu equipo o usarlo en un entorno de nube.

Esta configuración transforma 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 basados en búsqueda semántica
  3. Ayudar a los desarrolladores a encontrar implementaciones específicas o patrones de uso

Puedes poblar la base de datos almacenando descripciones en lenguaje natural de fragmentos de código (en el parámetro information) junto con el código real (en la propiedad metadata.code), y luego buscarlos usando consultas en lenguaje natural que describan lo que estás buscando.

[!NOTE] Las descripciones de herramientas proporcionadas arriba son ejemplos y pueden necesitar personalización para tu caso de uso específico. Considera ajustar las descripciones para que coincidan mejor con el flujo de trabajo de tu equipo y los tipos específicos de fragmentos de código que deseas almacenar y recuperar.

Si has instalado correctamente mcp-server-qdrant, pero aún no puedes hacer que funcione con Cursor, considera crear las reglas de Cursor para que las herramientas MCP se usen siempre cuando el agente produzca un nuevo fragmento de código. Puedes restringir las reglas para que solo funcionen con ciertos tipos de archivo, para evitar usar el servidor MCP para documentación u otros tipos de contenido.

Uso con Claude Code

Puedes mejorar las capacidades de Claude Code conectándolo a este servidor MCP, habilitando la búsqueda semántica sobre tu base de código existente.

Configuración de mcp-server-qdrant

  1. Agrega 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 el servidor se haya agregado:

    claude mcp list

Uso de la búsqueda semántica de código en Claude Code

Las descripciones de herramientas, especificadas en TOOL_STORE_DESCRIPTION y TOOL_FIND_DESCRIPTION, guían a Claude Code sobre cómo usar el servidor MCP. Las proporcionadas anteriormente son ejemplos y pueden necesitar personalización para tu caso de uso específico. Sin embargo, Claude Code ya debería ser capaz de:

  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 usando lenguaje natural.

Ejecutar el servidor MCP en modo de desarrollo

El servidor MCP se puede ejecutar en modo de desarrollo usando el comando mcp dev. Esto iniciará el servidor y abrirá el inspector de MCP en tu navegador.

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

Uso con VS Code

Para una instalación con un clic, haz clic en uno de los botones de instalación a continuación:

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

Agrega el siguiente bloque JSON a tu archivo de Configuración de Usuario (JSON) en VS Code. Puedes hacer esto presionando 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, agrega esta configuración en su lugar:

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

Alternativamente, 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 la configuración del 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 sobre cómo se podría mejorar mcp-server-qdrant, o deseas informar un error, ¡abre un issue! Nos encantaría recibir todas y cada una de las contribuciones.

Pruebas de mcp-server-qdrant localmente

El inspector de MCP es una herramienta de desarrollador para probar y depurar servidores MCP. Ejecuta tanto una interfaz de usuario de cliente (puerto predeterminado 5173) como un servidor proxy MCP (puerto predeterminado 3000). Abre la interfaz de usuario del cliente en tu navegador para usar el inspector.

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

Una vez iniciado, abre tu navegador en http://localhost:5173 para acceder a la interfaz del inspector.

Licencia

Este servidor MCP está licenciado bajo la Licencia Apache 2.0. Esto significa que eres libre de usar, modificar y distribuir el software, sujeto a los términos y condiciones de la Licencia Apache 2.0. Para más detalles, consulta el archivo LICENSE en el repositorio del proyecto.

Privacidad y soporte