qdrant-mcp-ollama

Un servidor de Model Context Protocol (MCP) para la base de datos vectorial de Qdrant que utiliza Ollama para embeddings acelerados por GPU.

¿Por qué no el mcp-server-qdrant oficial?

El servidor MCP oficial de Qdrant usa FastEmbed para los embeddings, lo que:

• Solo funciona en CPU — es lento en bases de código grandes y no aprovecha las GPU modernas

• Utiliza un modelo pequeño (all-MiniLM-L6-v2, 384 dimensiones) — embeddings de menor calidad

• Protección de un solo proceso en modo local — solo un cliente MCP puede acceder a la base de datos a la vez

Este servidor resuelve los tres problemas:

Related MCP server: Claude Context MCP

Arquitectura

┌──────────────┐     ┌────────────────────┐     ┌─────────────┐
│  MCP Client   │────>│  qdrant-mcp-ollama │────>│   Ollama    │
│ (Claude Code, │     │    (server.py)      │     │  (GPU)      │
│  Kilo Code,   │<────│                    │     └─────────────┘
│  Cursor, etc) │     └────────┬───────────┘
└──────────────┘              │
                              v
                   ┌────────────────────┐
                   │   Qdrant Server    │
                   │  (Docker, :6333)   │
                   │  Storage: local    │
                   │  disk / cloud      │
                   └────────────────────┘

Requisitos previos

• Ollama — instalado y en ejecución, con un modelo de embeddings descargado mediante ollama pull

• Docker — para ejecutar el servidor de Qdrant

• uv — gestor de paquetes de Python (recomendado) o pip

Inicio rápido

1. Descarga un modelo de embeddings en Ollama

ollama pull bge-m3

2. Inicia el servidor de Qdrant

docker run -d --name qdrant-server \
  -p 6333:6333 -p 6334:6334 \
  -v qdrant-storage:/qdrant/storage \
  --restart unless-stopped \
  qdrant/qdrant:latest

3. Ejecuta el servidor MCP

# No install needed — uv downloads dependencies on-the-fly:
QDRANT_URL="http://localhost:6333" \
EMBEDDING_MODEL="bge-m3" \
uv run --with fastmcp --with qdrant-client --with httpx python server.py

4. Indexa una base de código

uv run --with qdrant-client --with httpx python embed_codebase.py \
  /path/to/your/project my-project --preset python

5. Busca desde tu cliente MCP

Una vez configurado (consulta las secciones de abajo), pregúntale a tu asistente de IA:

"Busca la lógica de autenticación en la base de código"

Utilizará la herramienta qdrant_find para devolver fragmentos de código semánticamente relevantes.

Configurar el servidor de Qdrant

Opción A: Docker (recomendado)

Almacena los datos en una unidad concreta (p. ej., E: en Windows):

# Create storage directories
mkdir -p E:/qdrant-storage E:/qdrant-snapshots

# Start Qdrant with persistent storage
docker run -d --name qdrant-server \
  -p 6333:6333 -p 6334:6334 \
  -v E:/qdrant-storage:/qdrant/storage \
  -v E:/qdrant-snapshots:/qdrant/snapshots \
  --restart unless-stopped \
  qdrant/qdrant:latest

En Linux/macOS:

docker run -d --name qdrant-server \
  -p 6333:6333 -p 6334:6334 \
  -v ~/qdrant-storage:/qdrant/storage \
  --restart unless-stopped \
  qdrant/qdrant:latest

La opción --restart unless-stopped hace que Qdrant se inicie automáticamente con Docker Desktop.

Comprobación de funcionamiento:

docker ps --filter name=qdrant-server
# Or open http://localhost:6333/dashboard in your browser

Opción B: Qdrant Cloud

Regístrate en cloud.qdrant.io y obtén tu URL y clave de API. Después define:

QDRANT_URL="https://your-cluster.cloud.qdrant.io:6333"
QDRANT_API_KEY="your-api-key"

Nota: la variable de entorno QDRANT_API_KEY se transfiere automáticamente al cliente de Qdrant.

Indexar una base de código

El script embed_codebase.py escanea un directorio, divide los archivos fuente en fragmentos y los indexa por lotes en Qdrant utilizando Ollama y la GPU.

Uso básico

uv run --with qdrant-client --with httpx python embed_codebase.py <directory> <collection-name>

Uso de presets de extensiones

# Python project
python embed_codebase.py ./my-api api-backend --preset python

# Full-stack web project
python embed_codebase.py ./my-app frontend --preset web

# R / bioinformatics project
python embed_codebase.py ./analysis bio-analysis --preset r

# Everything
python embed_codebase.py ./mono-repo all-code --preset all

Extensiones personalizadas

python embed_codebase.py ./project my-collection --extensions .py .sql .sh .yaml

Presets disponibles

Si no se proporciona --preset ni --extensions, el script detecta automáticamente los tipos de archivo.

Todas las opciones

usage: embed_codebase.py <directory> <collection> [options]

positional arguments:
  directory              Path to the codebase directory
  collection             Qdrant collection name

options:
  --extensions EXT [EXT ...]  File extensions to include (e.g. .py .ts)
  --preset PRESET             Use a preset group of extensions
  --model MODEL               Ollama embedding model (default: bge-m3)
  --qdrant-url URL            Qdrant server URL (default: http://localhost:6333)
  --ollama-url URL            Ollama server URL (default: http://localhost:11434)
  --chunk-size N              Max lines per chunk (default: 80)
  --chunk-overlap N           Overlap lines between chunks (default: 10)
  --batch-size N              Upload batch size for Qdrant (default: 500)
  --append                    Append to existing collection instead of replacing

Modo append

Por defecto, al volver a ejecutar el script se reemplaza la colección. Usa --append para añadir a una colección existente:

# First embed
python embed_codebase.py ./src main-code --preset typescript

# Add more files later
python embed_codebase.py ./docs main-code --extensions .md --append

Uso con varias bases de código

Utiliza colecciones separadas para cada base de código y consigue que los resultados de búsqueda estén delimitados y sean relevantes:

# Project A
python embed_codebase.py ~/projects/api-server api-server --preset python

# Project B
python embed_codebase.py ~/projects/web-app web-app --preset web

# Project C
python embed_codebase.py ~/projects/data-pipeline data-pipeline --preset python

Al configurar el servidor MCP:

• Sin COLLECTION_NAME: de versión por consulta. Es ideal cuando un mismo servidor MCP da servicio a varios proyectos.

• Con COLLECTION_NAME: se usa automáticamente una colección por defecto. Configúralo por proyecto si tu cliente MCP admite la configuración por proyecto.

Configurar Claude Code

Añade el servidor MCP

claude mcp add qdrant -s user \
  -e QDRANT_URL="http://localhost:6333" \
  -e OLLAMA_URL="http://localhost:11434" \
  -e EMBEDDING_MODEL="bge-m3" \
  -- uv run --with fastmcp --with qdrant-client --with httpx \
     python /path/to/qdrant-mcp-ollama/server.py

Reemplaza /path/to/qdrant-mcp-ollama/ por la ruta real donde clonaste este repositorio.

Con una colección por defecto

Si trabajas principalmente en un solo proyecto:

claude mcp add qdrant -s user \
  -e QDRANT_URL="http://localhost:6333" \
  -e OLLAMA_URL="http://localhost:11434" \
  -e EMBEDDING_MODEL="bge-m3" \
  -e COLLECTION_NAME="my-project" \
  -- uv run --with fastmcp --with qdrant-client --with httpx \
     python /path/to/qdrant-mcp-ollama/server.py

Verificación

claude mcp list
# Should show: qdrant: ... ✓ Connected

claude mcp get qdrant
# Shows full configuration details

Uso en Claude Code

Cuando esté configurado, Claude Code puede usar estas herramientas:

• qdrant_store — Guarda información: "Almacena este patrón de autenticación en Qdrant"

• qdrant_find — Busca: "Encuentra código relacionado con migraciones de base de datos"

En configuraciones con múltiples colecciones (sin colección por defecto), especifica la colección:

"Busca la lógica de limitación de peticiones en la colección api-server"

Configurar Kilo Code (extensión de VS Code)

Kilo Code es una extensión de VS Code con soporte MCP integrado.

Opción 1: Configuración manual de MCP

1. Abre la configuración de Kilo Code en VS Code.

2. Ve a la configuración de servidores MCP.

3. Añade un nuevo servidor con:

4. Define las variables de entorno:

Opción 2: settings.json de VS Code

Añade a tu settings.json de VS Code (Ctrl+Shift+P > Preferencias: Abrir Configuración de Usuario (JSON)):

{
  "kilocode.mcpServers": {
    "qdrant": {
      "command": "uv",
      "args": [
        "run", "--with", "fastmcp", "--with", "qdrant-client", "--with", "httpx",
        "python", "/path/to/qdrant-mcp-ollama/server.py"
      ],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "OLLAMA_URL": "http://localhost:11434",
        "EMBEDDING_MODEL": "bge-m3",
        "COLLECTION_NAME": "my-project"
      }
    }
  }
}

Configuración por proyecto en Kilo Code

Para configuraciones con múltiples bases de código, configura Kilo Code en el ámbito de proyecto (no global) con un COLLECTION_NAME específico de cada proyecto. Así, cada espacio de trabajo buscará únicamente en su propia base de código.

Configurar otros clientes MCP

Cursor / Windsurf

Ejecuta el servidor con transporte SSE para clientes con capacidad de conexión remota:

QDRANT_URL="http://localhost:6333" \
OLLAMA_URL="http://localhost:11434" \
EMBEDDING_MODEL="bge-m3" \
FASTMCP_PORT=8000 \
uv run --with fastmcp --with qdrant-client --with httpx \
  python server.py --transport sse

Luego, en la configuración de MCP de Cursor/Windsurf, conéctate a: http://localhost:8000/sse

Cliente MCP genérico (stdio)

El transporte predeterminado es stdio. Cualquier cliente MCP que admita stdio puede usar este servidor ejecutando:

uv run --with fastmcp --with qdrant-client --with httpx python server.py

Referencia de configuración

Variables de entorno del servidor MCP

Elección del modelo de embeddings

Todos los modelos siguientes se descargan con ollama pull <model>:

Recomendación: empieza con bge-m3. Se comporta bien con código, admite contenido multilingüe (comentarios en cualquier idioma) y equilibra calidad y velocidad.

Importante: el modelo de embeddings usado para indexar una colección debe coincidir con el modelo usado en las consultas. Si vuelves a indexar con un modelo diferente, elimina y vuelve a crear la colección.

Uso de GPU

Los modelos más grandes utilizan más GPU. Si tu GPU está infrautilizada:

• Cambia de nomic-embed-text (274 MB) a bge-m3 (1,2 GB) o a un modelo mayor.

• El script de indexación envía todos los textos en un solo lote para maximizar la saturación de la GPU.

• En las consultas individuales (a través de qdrant_find), los picos de GPU son breves y normales; indexar una sola consulta toma milisegundos.

Comprueba el uso de GPU: nvidia-smi (NVIDIA) o rocm-smi (AMD)

Herramientas MCP

qdrant_store

Almacena información en la base de datos de Qdrant.

qdrant_find

Busca información relevante mediante similitud semántica.

Solución de problemas

«Connection closed» / el servidor MCP no se inicia

• ¿Está Ollama ejecutándose? Compruébalo con ollama list. Si es necesario, inícialo con ollama serve.

• ¿Se ha descargado el modelo de embeddings? Ejecuta ollama pull bge-m3.

• ¿Está Qdrant ejecutuado? Compruébalo con docker ps --filter name=qdrant-server.

«La colección no existe»

La colección se crea al ejecutar el script de indexación o en la primera llamada a qdrant_store. Haz una de estas dos cosas:

• Ejecuta embed_codebase.py para indexar tu base de código en primer lugar.

• O guarda algo con qdrant_store para que la colección se cree automáticamente.

Errores de dimensiones

Esto sucede cuando la colección se creó con un modelo de embeddings pero se consulta con otro. Solución:

1. Elimina la colección: visita http://localhost:6333/dashboard.

2. Vuelve a indexar con el modelo correcto.

3. Asegúrate de que EMBEDDING_MODEL en la configuración del servidor MCP coincide con el que usaste para indexar.

«La carpeta de almacenamiento ya está en uso por otra instancia»

Este mensaje es del oficial mcp-server-qdrant cuando se utiliza en modo local (QDRANT_LOCAL_PATH). Este proyecto evita ese problema conectando a un servidor de Qdrant mediante URL. Asegúrate de no ejecutar ambos servidores apuntando a la misma ruta local.

Indexación lenta / GPU

Usa modelos más grandes y verifica con nvidia-smi (NVIDIA) o rocm-smi (AMD).

• Usa un modelo más grande: bge-m3 (1.2 GB) en lugar de nomic-embed-text (274 MB)

• El script de incrustación envía todos los textos en un solo lote — si tienes miles de fragmentos, esto maximiza el uso de la GPU

• Para bases de código muy grandes (10,000+ archivos), considera dividir en varias ejecuciones por directorio

Licencia

Apache License 2.0 — ver LICENSE.