Servidor MCP de Qdrant

Un servidor de Model Context Protocol (MCP) que proporciona capacidades de búsqueda semántica utilizando la base de datos vectorial Qdrant con múltiples proveedores de embeddings.

Características

• Configuración cero: Funciona de inmediato con Ollama; no se requieren claves API

• Privacidad ante todo: Embeddings y almacenamiento vectorial locales; los datos nunca salen de su máquina

• Vectorización de código: Indexación inteligente de bases de código con fragmentación (chunking) consciente de AST y búsqueda semántica de código

• Búsqueda en el historial de Git: Indexe el historial de commits para realizar búsquedas semánticas sobre cambios, correcciones y patrones anteriores

• Búsqueda avanzada: Búsqueda contextual (código + git con correlaciones) y búsqueda federada en múltiples repositorios

• Múltiples proveedores: Ollama (predeterminado), OpenAI, Cohere y Voyage AI

• Búsqueda híbrida: Combine la búsqueda semántica y por palabras clave para obtener mejores resultados

• Búsqueda semántica: Búsqueda en lenguaje natural con filtrado de metadatos

• Indexación incremental: Actualizaciones eficientes; solo se reindexan los archivos modificados

• Prompts configurables: Cree prompts personalizados para flujos de trabajo guiados sin cambios en el código

• Limitación de tasa (Rate Limiting): Estrangulamiento inteligente con retroceso exponencial

• CRUD completo: Cree, busque y gestione colecciones y documentos

• Registro estructurado: Registro JSON a través de Pino con niveles de registro configurables

• Despliegue flexible: Ejecución local (stdio) o como servidor HTTP remoto

• Autenticación con clave API: Conéctese a instancias de Qdrant seguras (Qdrant Cloud, autohospedado con claves API)

Related MCP server: MCP Qdrant Server with OpenAI Embeddings

Inicio rápido

Requisitos previos

• Node.js 22.x o 24.x

• Podman o Docker con soporte para Compose

Instalación

# Clone and install
git clone https://github.com/mhalder/qdrant-mcp-server.git
cd qdrant-mcp-server

# Node 22.x
npm install

# Node 24.x (requires C++20 flag for native module compilation)
CXXFLAGS='-std=c++20' npm install

# Start services (choose one)
podman compose up -d   # Using Podman
docker compose up -d   # Using Docker

# Pull the embedding model
podman exec ollama ollama pull nomic-embed-text  # Podman
docker exec ollama ollama pull nomic-embed-text  # Docker

# Build
npm run build

Configuración

Configuración local (transporte stdio)

claude mcp add --transport stdio qdrant -- node /path/to/qdrant-mcp-server/build/index.js

O añádalo a ~/.claude.json:

{
  "mcpServers": {
    "qdrant": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/qdrant-mcp-server/build/index.js"]
    }
  }
}

Para Qdrant Cloud o instancias seguras, añada --env QDRANT_API_KEY=su-clave o configúrelo en la configuración de entorno.

Pruébelo:

Create a collection called "notes" and add a document about machine learning

Habilitar prompts de ejemplo: Copie prompts.example.json a prompts.json y reinicie. Use /prompt para listar los prompts disponibles.

Configuración remota (transporte HTTP)

⚠️ Advertencia de seguridad: Al desplegar el transporte HTTP en producción:

• Siempre ejecute detrás de un proxy inverso (nginx, Caddy) con HTTPS

• Implemente autenticación/autorización a nivel de proxy

• Use firewalls para restringir el acceso a redes de confianza

• Nunca exponga directamente a la internet pública sin protección

• Considere implementar limitación de tasa a nivel de proxy

• Supervise los registros del servidor en busca de actividad sospechosa

Inicie el servidor:

TRANSPORT_MODE=http HTTP_PORT=3000 node build/index.js

Opción 1: Usando claude mcp add

claude mcp add --transport http qdrant http://your-server:3000/mcp

Opción 2: Añadir a ~/.claude.json

{
  "mcpServers": {
    "qdrant": {
      "type": "http",
      "url": "http://your-server:3000/mcp"
    }
  }
}

Usando un proveedor diferente:

"env": {
  "EMBEDDING_PROVIDER": "openai",  // or "cohere", "voyage"
  "OPENAI_API_KEY": "sk-...",      // provider-specific API key
  "QDRANT_URL": "http://localhost:6333"
}

Reinicie después de realizar cambios.

Consulte la sección Configuración avanzada a continuación para ver todas las opciones.

Herramientas

Gestión de colecciones

Operaciones de documentos

Vectorización de código

Historial de Git

Búsqueda avanzada

Recursos

• qdrant://collections - Listar todas las colecciones

• qdrant://collection/{name} - Detalles de la colección

Prompts configurables

Cree prompts personalizados adaptados a sus casos de uso específicos sin modificar el código. Los prompts proporcionan flujos de trabajo guiados para tareas comunes.

Nota: De forma predeterminada, el servidor busca prompts.json en el directorio raíz del proyecto. Si el archivo existe, los prompts se cargan automáticamente. Puede especificar una ruta personalizada usando la variable de entorno PROMPTS_CONFIG_FILE.

Configuración

1. Cree un archivo de configuración de prompts (p. ej., prompts.json en la raíz del proyecto):

   Consulte prompts.example.json para ver configuraciones de ejemplo que puede copiar y personalizar.

2. Configure el servidor (opcional - solo necesario para rutas personalizadas):

Si coloca prompts.json en la raíz del proyecto, no se necesita configuración adicional. Para usar una ruta personalizada:

{
  "mcpServers": {
    "qdrant": {
      "command": "node",
      "args": ["/path/to/qdrant-mcp-server/build/index.js"],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "PROMPTS_CONFIG_FILE": "/custom/path/to/prompts.json"
      }
    }
  }
}

3. Use prompts en su asistente de IA:

Claude Code:

/mcp__qdrant__find_similar_docs papers "neural networks" 10

VSCode:

/mcp.qdrant.find_similar_docs papers "neural networks" 10

Prompts de ejemplo

Consulte prompts.example.json para ver prompts listos para usar, incluyendo:

• setup_rag_collection - Crear colecciones optimizadas para RAG

• analyze_and_optimize - Perspectivas y recomendaciones de la colección

• compare_search_strategies - Comparación de búsqueda semántica vs híbrida

• migrate_to_hybrid - Guía de migración de colecciones

• debug_search_quality - Solucionar problemas de resultados de búsqueda deficientes

• build_knowledge_base - Documentación estructurada con metadatos

• index_git_history - Indexar el historial de commits del repositorio para búsqueda semántica

• search_project_history - Buscar en el historial de git para entender implementaciones de funciones

• investigate_code_with_history - Análisis profundo del código con búsqueda contextual

• cross_repo_search - Buscar patrones en múltiples repositorios

• trace_feature_evolution - Rastrear cómo evolucionaron las funciones con el tiempo

• security_audit_search - Encontrar código y correcciones relacionados con la seguridad

Sintaxis de plantillas

Las plantillas usan marcadores de posición {{variable}}:

• Los argumentos obligatorios deben proporcionarse

• Los argumentos opcionales usan valores predeterminados si no se especifican

• Las variables desconocidas se dejan tal cual en la salida

Vectorización de código

Indexe y busque de forma inteligente en su base de código utilizando la búsqueda semántica de código. Perfecto para el desarrollo asistido por IA, la exploración de código y la comprensión de grandes bases de código.

Características

• Fragmentación consciente de AST: División inteligente de código en límites de función/clase usando tree-sitter

• Soporte multilingüe: Más de 35 tipos de archivos, incluyendo TypeScript, Python, Java, Go, Rust, C++, y más

• Actualizaciones incrementales: Solo reindexe los archivos cambiados para actualizaciones rápidas

• Patrones de ignorar inteligentes: Respeta los archivos .gitignore, .dockerignore y .contextignore personalizados

• Búsqueda semántica: Consultas en lenguaje natural para encontrar código relevante

• Filtrado de metadatos: Filtre por tipo de archivo, patrones de ruta o lenguaje

• Local-First: Todo el procesamiento ocurre localmente; su código nunca sale de su máquina

Inicio rápido

1. Indexe su base de código:

# Via Claude Code MCP tool
/mcp__qdrant__index_codebase /path/to/your/project

2. Busque en su código:

# Natural language search
/mcp__qdrant__search_code /path/to/your/project "authentication middleware"

# Filter by file type
/mcp__qdrant__search_code /path/to/your/project "database schema" --fileTypes .ts,.js

# Filter by path pattern
/mcp__qdrant__search_code /path/to/your/project "API endpoints" --pathPattern src/api/**

3. Actualice después de los cambios:

# Incrementally re-index only changed files
/mcp__qdrant__reindex_changes /path/to/your/project

Ejemplos de uso

Indexar un proyecto TypeScript

// The MCP tool automatically:
// 1. Scans all .ts, .tsx, .js, .jsx files
// 2. Respects .gitignore patterns (skips node_modules, dist, etc.)
// 3. Chunks code at function/class boundaries
// 4. Generates embeddings using your configured provider
// 5. Stores in Qdrant with metadata (file path, line numbers, language)

index_codebase({
  path: "/workspace/my-app",
  forceReindex: false, // Set to true to re-index from scratch
});

// Output:
// ✓ Indexed 247 files (1,823 chunks) in 45.2s

Buscar código de autenticación

search_code({
  path: "/workspace/my-app",
  query: "how does user authentication work?",
  limit: 5,
});

// Results include file path, line numbers, and code snippets:
// [
//   {
//     filePath: "src/auth/middleware.ts",
//     startLine: 15,
//     endLine: 42,
//     content: "export async function authenticateUser(req: Request) { ... }",
//     score: 0.89,
//     language: "typescript"
//   },
//   ...
// ]

Buscar con filtros

// Only search TypeScript files
search_code({
  path: "/workspace/my-app",
  query: "error handling patterns",
  fileTypes: [".ts", ".tsx"],
  limit: 10,
});

// Only search in specific directories
search_code({
  path: "/workspace/my-app",
  query: "API route handlers",
  pathPattern: "src/api/**",
  limit: 10,
});

Reindexación incremental

// After making changes to your codebase
reindex_changes({
  path: "/workspace/my-app",
});

// Output:
// ✓ Updated: +3 files added, ~5 files modified, -1 files deleted
// ✓ Chunks: +47 added, -23 deleted in 8.3s

Comprobar el estado de indexación

get_index_status({
  path: "/workspace/my-app",
});

// Output:
// {
//   status: "indexed",      // "not_indexed" | "indexing" | "indexed"
//   isIndexed: true,        // deprecated: use status instead
//   collectionName: "code_a3f8d2e1",
//   chunksCount: 1823,
//   filesCount: 247,
//   lastUpdated: "2025-01-30T10:15:00Z",
//   languages: ["typescript", "javascript", "json"]
// }

Lenguajes soportados

Lenguajes de programación (más de 35 tipos de archivos):

• Web: TypeScript, JavaScript, Vue, Svelte

• Backend: Python, Java, Go, Rust, Ruby, PHP

• Sistemas: C, C++, C#

• Móvil: Swift, Kotlin, Dart

• Funcional: Scala, Clojure, Haskell, OCaml

• Scripting: Bash, Shell, Fish

• Datos: SQL, GraphQL, Protocol Buffers

• Configuración: JSON, YAML, TOML, XML, Markdown

Consulte la configuración para ver la lista completa y las opciones de personalización.

Patrones de ignorar personalizados

Cree un archivo .contextignore en la raíz de su proyecto para especificar patrones adicionales a ignorar:

# .contextignore
**/test/**
**/*.test.ts
**/*.spec.ts
**/fixtures/**
**/mocks/**
**/__tests__/**

Mejores prácticas

1. Indexe una vez, actualice incrementalmente: Use index_codebase para la indexación inicial, luego reindex_changes para las actualizaciones

2. Use filtros: Reduzca el alcance de la búsqueda con fileTypes y pathPattern para obtener mejores resultados

3. Consultas significativas: Use lenguaje natural que describa lo que está buscando (p. ej., "agrupación de conexiones de base de datos" en lugar de "db")

4. Compruebe el estado primero: Use get_index_status para verificar que una base de código esté indexada antes de buscar

5. Embedding local: Use Ollama (predeterminado) para mantener todo local y privado

Rendimiento

Rendimiento típico en una computadora portátil moderna (Apple M1/M2 o similar):

Nota: El tiempo de indexación varía según el proveedor de embedding. Ollama (local) es el más rápido para la indexación inicial.

Búsqueda en el historial de Git

Indexe y busque en el historial de commits de git de su repositorio usando lenguaje natural. Perfecto para encontrar correcciones pasadas, entender patrones de cambio y aprender de trabajos anteriores.

Características

• Búsqueda semántica de commits: Encuentre commits describiendo lo que busca en lenguaje natural

• Clasificación de commits convencionales: Clasificación automática de commits (feat, fix, refactor, etc.)

• Actualizaciones incrementales: Solo indexe nuevos commits para actualizaciones eficientes

• Filtrado enriquecido: Filtre por tipo de commit, autor o rango de fechas

• Extracción de metadatos: Incluye archivos cambiados, inserciones/eliminaciones y contexto completo del commit

Inicio rápido

1. Indexe el historial de git de su repositorio:

# Via Claude Code MCP tool
/mcp__qdrant__index_git_history /path/to/your/repo

2. Busque commits relevantes:

# Natural language search
/mcp__qdrant__search_git_history /path/to/your/repo "fix authentication bug"

# Filter by commit type
/mcp__qdrant__search_git_history /path/to/your/repo "database optimization" --commitTypes fix,perf

# Filter by author
/mcp__qdrant__search_git_history /path/to/your/repo "API changes" --authors "john@example.com"

3. Mantenga el índice actualizado:

# Incrementally index only new commits
/mcp__qdrant__index_new_commits /path/to/your/repo

Casos de uso

• Encontrar correcciones similares: "¿Cómo se solucionó antes el problema de puntero nulo en la autenticación?"

• Entender patrones: "¿Qué refactorización se hizo en la capa de base de datos?"

• Aprender de la historia: "Muéstrame ejemplos de implementaciones de endpoints de API"

• Arqueología de código: "¿Qué cambios se hicieron en el sistema de pagos el año pasado?"

Búsqueda avanzada

Combine la búsqueda de código y de historial de git para una comprensión más profunda de la base de código. Requiere que los repositorios estén indexados primero con index_codebase e index_git_history.

• Búsqueda contextual: Consulte código + historial de git juntos con correlaciones automáticas archivo-commit

• Búsqueda federada: Busque en múltiples repositorios con clasificación RRF

Consulte Ejemplos de búsqueda avanzada para obtener uso detallado, flujos de trabajo y escenarios.

Ejemplos

Consulte el directorio examples/ para ver guías detalladas:

• **[Uso