Qdrant MCP

mcp-server-qdrant: Un servidor MCP de Qdrant

El Protocolo de Contexto de Modelo (MCP) es un protocolo abierto que permite una 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 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 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
   • Almacena información en la base de datos Qdrant
   • Entrada:
     • information (string): Información a almacenar
     • metadata (JSON): Metadatos opcionales para almacenar
     • collection_name (string): Nombre de la colección en la que almacenar 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 a utilizar para la búsqueda
     • collection_name (string): Nombre de la colección en la que almacenar 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, utilizado para seleccionar el protocolo de transporte.

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

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 Qdrant local (alternativa a QDRANT_URL)	Ninguno
EMBEDDING_PROVIDER	Proveedor de embeddings a utilizar (actualmente solo se admite "fastembed")	fastembed
EMBEDDING_MODEL	Nombre del modelo de embeddings a utilizar	sentence-transformers/all-MiniLM-L6-v2
TOOL_STORE_DESCRIPTION	Descripción personalizada para la herramienta de almacenamiento	Consulta el valor predeterminado en settings.py
TOOL_FIND_DESCRIPTION	Descripción personalizada para la herramienta de búsqueda	Consulta el valor predeterminado en settings.py
QDRANT_SEARCH_LIMIT	Número máximo de resultados a devolver de la búsqueda	10
QDRANT_READ_ONLY	Habilita el modo de solo lectura (desactiva 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 entorno	Descripción	Valor predeterminado
FASTMCP_LOG_LEVEL	Establece el nivel de registro (DEBUG, INFO, WARNING, ERROR, CRITICAL)	INFO
FASTMCP_SERVER_DEBUG	Habilita el modo de depuración	false
FASTMCP_SERVER_HOST	Dirección de host para 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] La configuración específica del servidor utiliza el prefijo FASTMCP_SERVER_. Esto puede cambiar en versiones futuras.

Instalación

Usando uvx

Al usar uvx no se necesita 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 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, 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 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_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 a través de Smithery

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, 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 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 embeddings sentence-transformers/all-MiniLM-L6-v2 para codificar los recuerdos. Por el momento, solo se admiten modelos 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.

Usar 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 tu configuración apuntando a este servidor en ejecución usando el protocolo de transporte SSE. La descripción sobre 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 la 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 buscar usando consultas en lenguaje natural que describan lo que estás buscando.

[!NOTE] Las descripciones de las herramientas proporcionadas arriba son ejemplos y es posible que deban personalizarse 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, por favor considera crear las reglas de Cursor para que las herramientas MCP se usen siempre cuando el agente produce 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.

Usar con Claude Code

Puedes mejorar las capacidades de Claude Code conectándolo a este servidor MCP, habilitando la búsqueda semántica en 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 fue agregado:

   claude mcp list
   

Uso de la búsqueda de código semántica 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 proporcionadas arriba son ejemplos y es posible que deban personalizarse para tu caso de uso específico. Sin embargo, Claude Code 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 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

Usar con VS Code

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

Instalación manual

Agrega el siguiente bloque JSON a tu archivo de User Settings (JSON) en VS Code. Puedes hacerlo 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 mejorar mcp-server-qdrant, o deseas reportar un error, ¡abre un issue! Nos encantarían todas y cada una de las contribuciones.

Probar 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

• Política de privacidad
• Soporte