Qdrant MCP Server

oficial

Implementar una capa

Documentación

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 aplicaciones LLM y fuentes de datos y herramientas externas. Ya sea que estés construyendo un IDE potenciado por IA, mejorando una interfaz de chat o creando flujos de trabajo de IA personalizados, MCP proporciona 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 del Protocolo de Contexto de Modelo 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

qdrant-store
- Almacena información en la base de datos Qdrant
- Entrada:
  - information (string): Información a almacenar
  - metadata (JSON): Metadatos opcionales a almacenar
  - collection_name (string): Nombre de la colección donde almacenar la información. Este campo es obligatorio si no hay un nombre de colección por defecto. Si hay un nombre de colección por defecto, 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 a usar para la búsqueda
  - collection_name (string): Nombre de la colección donde almacenar la información. Este campo es obligatorio si no hay un nombre de colección por defecto. Si hay un nombre de colección por defecto, 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, usado para seleccionar el protocolo de transporte.

[!NOTE] No puedes proporcionar QDRANT_URL y QDRANT_LOCAL_PATH al mismo tiempo.

Nombre	Descripción	Valor por defecto
`QDRANT_URL`	URL del servidor Qdrant	Ninguno
`QDRANT_API_KEY`	Clave API para el servidor Qdrant	Ninguno
`COLLECTION_NAME`	Nombre de la colección por defecto a usar.	Ninguno
`QDRANT_LOCAL_PATH`	Ruta a la base de datos Qdrant local (alternativa a `QDRANT_URL`)	Ninguno
`EMBEDDING_PROVIDER`	Proveedor de embedding a usar (actualmente solo se soporta "fastembed")	`fastembed`
`EMBEDDING_MODEL`	Nombre del modelo de embedding a usar	`sentence-transformers/all-MiniLM-L6-v2`
`TOOL_STORE_DESCRIPTION`	Descripción personalizada para la herramienta de almacenamiento	Ver valor por defecto en `settings.py`
`TOOL_FIND_DESCRIPTION`	Descripción personalizada para la herramienta de búsqueda	Ver valor por defecto en `settings.py`
`QDRANT_SEARCH_LIMIT`	Número máximo de resultados a devolver de la búsqueda	`10`
`QDRANT_READ_ONLY`	Habilitar modo solo lectura (deshabilita la herramienta `qdrant-store`)	`false`

Variables de entorno de FastMCP

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

Variable de entorno	Descripción	Valor por defecto
`FASTMCP_LOG_LEVEL`	Establecer nivel de registro (DEBUG, INFO, WARNING, ERROR, CRITICAL)	`INFO`
`FASTMCP_SERVER_DEBUG`	Habilitar modo depuración	`false`
`FASTMCP_SERVER_HOST`	Dirección del host a la que vincular el servidor	`127.0.0.1`
`FASTMCP_SERVER_PORT`	Puerto en el que ejecutar el servidor	`8000`
`FASTMCP_SERVER_ON_DUPLICATE_RESOURCES`	Comportamiento para recursos duplicados (warn, error, replace, ignore)	`warn`
`FASTMCP_SERVER_ON_DUPLICATE_TOOLS`	Comportamiento para herramientas duplicadas (warn, error, replace, ignore)	`warn`
`FASTMCP_SERVER_ON_DUPLICATE_PROMPTS`	Comportamiento para prompts duplicados (warn, error, replace, ignore)	`warn`
`FASTMCP_SERVER_DEPENDENCIES`	Lista de dependencias a instalar en el entorno del servidor	`[]`

[!NOTE] Los ajustes específicos del servidor usan el prefijo FASTMCP_SERVER_. Esto puede cambiar en futuras versiones.

Instalación

Usando uvx

Al usar uvx no se necesita una 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 soporta 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 soportados:

stdio (por defecto): Transporte de entrada/salida estándar, solo puede ser usado por clientes MCP locales
sse: Transporte de Eventos Enviados por el Servidor, perfecto para clientes remotos
streamable-http: Transporte HTTP transmitible, perfecto para clientes remotos, más reciente que SSE

El transporte por defecto 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 por defecto 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 establecemos FASTMCP_SERVER_HOST="0.0.0.0" para hacer que el servidor escuche en todas las interfaces de red. Esto es necesario cuando se ejecuta el servidor en un contenedor Docker.

Instalación vía Smithery

Para instalar el Servidor MCP de Qdrant para Claude Desktop automáticamente vía 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 no existe.

Por defecto, el servidor usará el modelo de embedding sentence-transformers/all-MiniLM-L6-v2 para codificar memorias. Por el momento, solo se soportan modelos de FastEmbed.

Soporte para 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 Modelo.

Usando 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 sobre cómo añadir 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 la forma preferida de conectar Cursor/Windsurf al servidor MCP, ya que puede soportar conexiones remotas. Eso facilita compartir el servidor con tu equipo o usarlo en un entorno en la nube.

Esta configuración transforma 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 basados en búsqueda semántica
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 ser personalizadas 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 quieres almacenar y recuperar.

Si has instalado exitosamente el mcp-server-qdrant, pero aún no puedes hacerlo funcionar con Cursor, por favor 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 para ciertos tipos de archivo, para evitar usar el servidor MCP para la documentación u otros tipos de contenido.

Usando 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.

Configurando 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 el servidor fue añadido:
```
claude mcp list
```

Usando 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 arriba son ejemplos y pueden necesitar ser personalizadas para tu caso de uso específico. Sin embargo, Claude Code ya debería ser capaz de:

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

Ejecutar el servidor MCP en Modo Desarrollo

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

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

Usando con VS Code

Para instalación en un clic, haz clic en uno de los botones de instalación de abajo:

Instalación Manual

Añade 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, añade 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 quieres reportar un error, ¡abre un issue! Nos encantaría recibir todas y cada una de las contribuciones.

Probando `mcp-server-qdrant` localmente

El inspector MCP es una herramienta para desarrolladores para probar y depurar servidores MCP. Ejecuta tanto una interfaz de usuario cliente (puerto por defecto 5173) como un servidor proxy MCP (puerto por defecto 3000). Abre la interfaz de usuario 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, por favor consulta el archivo LICENSE en el repositorio del proyecto.