mcp-server-qdrant: Un servidor MCP de Qdrant

El Protocolo de Contexto de Modelo (MCP) es un protocolo abierto que permite una integración fluida entre las aplicaciones LLM y las fuentes de datos y herramientas externas. Ya sea que esté creando un IDE basado en IA, mejorando una interfaz de chat o creando flujos de trabajo de IA personalizados, MCP proporciona una forma estandarizada de conectar las aplicaciones 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 del Protocolo de Contexto de Modelo para el almacenamiento y la recuperación de memorias en el motor de búsqueda vectorial de Qdrant. Actúa como una capa de memoria semántica sobre la base de datos de Qdrant.

Componentes

Herramientas

qdrant-store
- Almacenar cierta información en la base de datos de Qdrant
- Aporte:
  - information (cadena): Información a almacenar
  - metadata (JSON): metadatos opcionales para almacenar
  - collection_name (cadena): Nombre de la colección donde se almacena 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.
- Devoluciones: Mensaje de confirmación
qdrant-find
- Recupere información relevante de la base de datos de Qdrant
- Aporte:
  - query (cadena): consulta que se utilizará para la búsqueda
  - collection_name (cadena): Nombre de la colección donde se almacena 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 de Qdrant como mensajes separados

Variables de entorno

La configuración del servidor se realiza mediante variables de entorno:

Nombre	Descripción	Valor predeterminado
`QDRANT_URL`	URL del servidor Qdrant	Ninguno
`QDRANT_API_KEY`	Clave API para el servidor Qdrant	Ninguno
`COLLECTION_NAME`	Nombre de la colección predeterminada a utilizar.	Ninguno
`QDRANT_LOCAL_PATH`	Ruta a la base de datos local de Qdrant (alternativa a `QDRANT_URL` )	Ninguno
`EMBEDDING_PROVIDER`	Proveedor de incrustación a utilizar (actualmente solo se admite "fastembed")	`fastembed`
`EMBEDDING_MODEL`	Nombre del modelo de incrustación a utilizar	`sentence-transformers/all-MiniLM-L6-v2`
`TOOL_STORE_DESCRIPTION`	Descripción personalizada para la herramienta de la tienda	Ver valor predeterminado en `settings.py`
`TOOL_FIND_DESCRIPTION`	Descripción personalizada para la herramienta de búsqueda	Ver valor predeterminado en `settings.py`

Nota: no puede proporcionar QDRANT_URL y QDRANT_LOCAL_PATH al mismo tiempo.

[!IMPORTANTE] ¡Ya no se admiten los argumentos de la línea de comandos! Utilice variables de entorno para toda la configuración.

Instalación

Uso de uvx

Al utilizar 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 pueden especificarse utilizando el indicador --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, que solo puede ser utilizado por clientes MCP locales
sse : Transporte de eventos enviados por el servidor, perfecto para clientes remotos

El transporte predeterminado es stdio si no se especifica.

Usando Docker

Hay un Dockerfile disponible para crear y ejecutar el servidor MCP:

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

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

Instalación mediante herrería

Para instalar Qdrant MCP Server para Claude Desktop automáticamente a través de 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, agregue la siguiente configuración a la sección "mcpServers" de su 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 no existe.

De forma predeterminada, el servidor utilizará el modelo de incrustación sentence-transformers/all-MiniLM-L6-v2 para codificar las memorias. Por el momento, solo se admiten los modelos FastEmbed .

Soporte para otras herramientas

Este servidor MCP se puede usar con cualquier cliente compatible con MCP. Por ejemplo, se puede usar con Cursor y VS Code , que ofrecen compatibilidad integrada con el Protocolo de Contexto de Modelo.

Uso con Cursor/Windsurf

Puede 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, puede configurar el servidor MCP en la configuración apuntando a este servidor en ejecución mediante el protocolo de transporte SSE. La descripción sobre cómo agregar un servidor MCP a Cursor se encuentra en la documentación de Cursor . Si ejecuta Cursor/Windsurf localmente, puede usar la siguiente URL:

http://localhost:8000/sse

[!TIP] Recomendamos el transporte SSE como método preferido para conectar Cursor/Windsurf al servidor MCP, ya que admite conexiones remotas. Esto facilita compartir el servidor con su equipo o usarlo en la nube.

Esta configuración transforma el servidor Qdrant MCP en una herramienta de búsqueda de código especializada que puede:

Almacenar fragmentos de código, documentación y detalles de implementación
Recupere ejemplos de código relevantes basados en la búsqueda semántica
Ayudar a los desarrolladores a encontrar implementaciones específicas o patrones de uso

Puede completar 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 utilizando consultas en lenguaje natural que describan lo que está buscando.

[!NOTA] Las descripciones de las herramientas proporcionadas anteriormente son ejemplos y podrían requerir ajustes para su caso de uso específico. Considere ajustar las descripciones para que se ajusten mejor al flujo de trabajo de su equipo y a los tipos específicos de fragmentos de código que desea almacenar y recuperar.

Si ha instalado correctamente mcp-server-qdrant , pero aún no consigue que funcione con Cursor, considere crear las reglas de Cursor para que las herramientas de MCP se utilicen siempre cuando el agente genere un nuevo fragmento de código. Puede restringir las reglas para que solo funcionen con ciertos tipos de archivo y así evitar usar el servidor MCP para la documentación u otro tipo de contenido.

Uso con Claude Code

Puede mejorar las capacidades de Claude Code conectándolo a este servidor MCP, lo que permite la búsqueda semántica en su base de código existente.

Configuración de mcp-server-qdrant

Agregue 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
Verifique que se agregó el servidor:
claude mcp list

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

Las descripciones de las herramientas, especificadas en TOOL_STORE_DESCRIPTION y TOOL_FIND_DESCRIPTION , guían a Claude Code sobre cómo usar el servidor MCP. Las descripciones anteriores son ejemplos y podrían requerir ajustes específicos para su caso de uso. Sin embargo, Claude Code ya debería poder:

Utilice la herramienta qdrant-store para almacenar fragmentos de código con descripciones.
Utilice la herramienta qdrant-find para buscar fragmentos de código relevantes utilizando lenguaje natural.

Ejecutar el servidor MCP en modo de desarrollo

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

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

Uso con VS Code

Para la instalación con un solo clic, haga clic en uno de los botones de instalación a continuación:

Instalación manual

Agrega el siguiente bloque JSON a tu archivo de configuración de usuario (JSON) en VS Code. Para ello, presiona Ctrl + Shift + P y escribe 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, puede crear un archivo .vscode/mcp.json en su 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, use 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}"
      }
    }
  }
}

Contribuyendo

Si tienes sugerencias para mejorar mcp-server-qdrant o quieres reportar un error, ¡crea un problema! Nos encantaría recibir cualquier contribución.

Probando `mcp-server-qdrant` localmente

El inspector MCP es una herramienta para desarrolladores que permite probar y depurar servidores MCP. Ejecuta una interfaz de cliente (puerto predeterminado: 5173) y un servidor proxy MCP (puerto predeterminado: 3000). Abra la interfaz de cliente en su navegador para usar el inspector.

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

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

Licencia

Este servidor MCP cuenta con la licencia Apache 2.0. Esto significa que puede usar, modificar y distribuir el software libremente, sujeto a los términos y condiciones de la licencia Apache 2.0. Para más detalles, consulte el archivo de licencia en el repositorio del proyecto.

mcp-server-qdrant

mcp-server-qdrant: Un servidor MCP de Qdrant

Descripción general

Componentes

Herramientas

Variables de entorno

Instalación

Uso de uvx

Protocolos de transporte

Usando Docker

Instalación mediante herrería

Configuración manual de Claude Desktop

Soporte para otras herramientas

Uso con Cursor/Windsurf

Uso con Claude Code

Configuración de mcp-server-qdrant

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

Ejecutar el servidor MCP en modo de desarrollo

Uso con VS Code

Instalación manual

Contribuyendo

Probando `mcp-server-qdrant` localmente

Licencia

Tools

Appeared in Searches

mcp-server-qdrant: Un servidor MCP de Qdrant

Descripción general

Componentes

Herramientas

Variables de entorno

Instalación

Uso de uvx

Protocolos de transporte

Usando Docker

Instalación mediante herrería

Configuración manual de Claude Desktop

Soporte para otras herramientas

Uso con Cursor/Windsurf

Uso con Claude Code

Configuración de mcp-server-qdrant

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

Ejecutar el servidor MCP en modo de desarrollo

Uso con VS Code

Instalación manual

Contribuyendo

Probando mcp-server-qdrant localmente

Licencia

Tools

Appeared in Searches

Probando `mcp-server-qdrant` localmente