Qdrant MCP-Server

Ein Model Context Protocol (MCP)-Server, der semantische Suchfunktionen unter Verwendung der Qdrant-Vektordatenbank mit mehreren Embedding-Anbietern bereitstellt.

Funktionen

• Keine Einrichtung erforderlich: Funktioniert sofort mit Ollama – keine API-Schlüssel erforderlich

• Datenschutz zuerst: Lokale Embeddings und Vektorspeicherung – Daten verlassen niemals Ihren Rechner

• Code-Vektorisierung: Intelligente Codebasis-Indizierung mit AST-bewusstem Chunking und semantischer Codesuche

• Git-Verlaufssuche: Indizieren Sie den Commit-Verlauf für die semantische Suche über vergangene Änderungen, Korrekturen und Muster

• Erweiterte Suche: Kontextbezogene Suche (Code + Git mit Korrelationen) und föderierte Suche über mehrere Repositories hinweg

• Mehrere Anbieter: Ollama (Standard), OpenAI, Cohere und Voyage AI

• Hybride Suche: Kombinieren Sie semantische Suche und Stichwortsuche für bessere Ergebnisse

• Semantische Suche: Natürlichsprachliche Suche mit Metadatenfilterung

• Inkrementelle Indizierung: Effiziente Aktualisierungen – nur geänderte Dateien werden neu indiziert

• Konfigurierbare Prompts: Erstellen Sie benutzerdefinierte Prompts für geführte Workflows ohne Codeänderungen

• Ratenbegrenzung: Intelligente Drosselung mit exponentiellem Backoff

• Vollständiges CRUD: Erstellen, suchen und verwalten Sie Sammlungen und Dokumente

• Strukturierte Protokollierung: JSON-Protokollierung über Pino mit konfigurierbaren Protokollebenen

• Flexible Bereitstellung: Lokal ausführen (stdio) oder als Remote-HTTP-Server

• API-Schlüssel-Authentifizierung: Verbindung zu gesicherten Qdrant-Instanzen (Qdrant Cloud, selbst gehostet mit API-Schlüsseln)

Related MCP server: MCP Qdrant Server with OpenAI Embeddings

Schnellstart

Voraussetzungen

• Node.js 22.x oder 24.x

• Podman oder Docker mit Compose-Unterstützung

Installation

# 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

Konfiguration

Lokale Einrichtung (stdio-Transport)

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

Oder fügen Sie es zu ~/.claude.json hinzu:

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

Für Qdrant Cloud oder gesicherte Instanzen fügen Sie --env QDRANT_API_KEY=ihr-schlüssel hinzu oder setzen Sie es in der Umgebungskonfiguration.

Ausprobieren:

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

Beispiel-Prompts aktivieren: Kopieren Sie prompts.example.json nach prompts.json und starten Sie neu. Verwenden Sie /prompt, um verfügbare Prompts aufzulisten.

Remote-Einrichtung (HTTP-Transport)

⚠️ Sicherheitshinweis: Beim Bereitstellen des HTTP-Transports in der Produktion:

• Immer hinter einem Reverse-Proxy (nginx, Caddy) mit HTTPS ausführen

• Implementieren Sie Authentifizierung/Autorisierung auf Proxy-Ebene

• Verwenden Sie Firewalls, um den Zugriff auf vertrauenswürdige Netzwerke zu beschränken

• Niemals ohne Schutz direkt dem öffentlichen Internet aussetzen

• Erwägen Sie die Implementierung einer Ratenbegrenzung auf Proxy-Ebene

• Überwachen Sie die Serverprotokolle auf verdächtige Aktivitäten

Starten Sie den Server:

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

Option 1: Verwendung von claude mcp add

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

Option 2: Hinzufügen zu ~/.claude.json

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

Verwendung eines anderen Anbieters:

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

Starten Sie nach Änderungen neu.

Siehe den Abschnitt Erweiterte Konfiguration unten für alle Optionen.

Tools

Sammlungsverwaltung

Dokumentenoperationen

Code-Vektorisierung

Git-Verlauf

Erweiterte Suche

Ressourcen

• qdrant://collections - Listet alle Sammlungen auf

• qdrant://collection/{name} - Sammlungsdetails

Konfigurierbare Prompts

Erstellen Sie benutzerdefinierte Prompts, die auf Ihre spezifischen Anwendungsfälle zugeschnitten sind, ohne den Code zu ändern. Prompts bieten geführte Workflows für häufige Aufgaben.

Hinweis: Standardmäßig sucht der Server nach prompts.json im Stammverzeichnis des Projekts. Wenn die Datei existiert, werden die Prompts automatisch geladen. Sie können einen benutzerdefinierten Pfad über die Umgebungsvariable PROMPTS_CONFIG_FILE angeben.

Einrichtung

1. Erstellen Sie eine Prompts-Konfigurationsdatei (z. B. prompts.json im Projektstammverzeichnis):

   Siehe prompts.example.json für Beispielkonfigurationen, die Sie kopieren und anpassen können.

2. Konfigurieren Sie den Server (optional – nur für benutzerdefinierte Pfade erforderlich):

Wenn Sie prompts.json im Projektstammverzeichnis ablegen, ist keine zusätzliche Konfiguration erforderlich. Um einen benutzerdefinierten Pfad zu verwenden:

{
  "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. Verwenden Sie Prompts in Ihrem KI-Assistenten:

Claude Code:

/mcp__qdrant__find_similar_docs papers "neural networks" 10

VSCode:

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

Beispiel-Prompts

Siehe prompts.example.json für sofort einsatzbereite Prompts, einschließlich:

• setup_rag_collection - Erstellen Sie RAG-optimierte Sammlungen

• analyze_and_optimize - Einblicke und Empfehlungen für Sammlungen

• compare_search_strategies - Vergleich zwischen semantischer und hybrider Suche

• migrate_to_hybrid - Leitfaden zur Sammlungsmigration

• debug_search_quality - Fehlerbehebung bei schlechten Suchergebnissen

• build_knowledge_base - Strukturierte Dokumentation mit Metadaten

• index_git_history - Indizieren Sie den Commit-Verlauf des Repositories für die semantische Suche

• search_project_history - Durchsuchen Sie den Git-Verlauf, um Funktionsimplementierungen zu verstehen

• investigate_code_with_history - Tauchen Sie mit kontextbezogener Suche tief in den Code ein

• cross_repo_search - Suchen Sie nach Mustern über mehrere Repositories hinweg

• trace_feature_evolution - Verfolgen Sie, wie sich Funktionen im Laufe der Zeit entwickelt haben

• security_audit_search - Finden Sie sicherheitsrelevanten Code und Korrekturen

Vorlagensyntax

Vorlagen verwenden {{variable}}-Platzhalter:

• Erforderliche Argumente müssen bereitgestellt werden

• Optionale Argumente verwenden Standardwerte, falls nicht angegeben

• Unbekannte Variablen bleiben in der Ausgabe unverändert

Code-Vektorisierung

Indizieren und durchsuchen Sie Ihre Codebasis intelligent mithilfe der semantischen Codesuche. Perfekt für KI-gestützte Entwicklung, Code-Exploration und das Verständnis großer Codebasen.

Funktionen

• AST-bewusstes Chunking: Intelligente Code-Aufteilung an Funktions-/Klassengrenzen unter Verwendung von tree-sitter

• Mehrsprachige Unterstützung: Über 35 Dateitypen, einschließlich TypeScript, Python, Java, Go, Rust, C++ und mehr

• Inkrementelle Aktualisierungen: Nur geänderte Dateien werden für schnelle Aktualisierungen neu indiziert

• Intelligente Ignorier-Muster: Respektiert .gitignore, .dockerignore und benutzerdefinierte .contextignore-Dateien

• Semantische Suche: Natürlichsprachliche Abfragen, um relevanten Code zu finden

• Metadatenfilterung: Filtern nach Dateityp, Pfadmustern oder Sprache

• Lokal-zuerst: Die gesamte Verarbeitung erfolgt lokal – Ihr Code verlässt niemals Ihren Rechner

Schnellstart

1. Indizieren Sie Ihre Codebasis:

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

2. Durchsuchen Sie Ihren Code:

# 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. Aktualisieren Sie nach Änderungen:

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

Anwendungsbeispiele

Indizieren eines TypeScript-Projekts

// 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

Suche nach Authentifizierungscode

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"
//   },
//   ...
// ]

Suche mit Filtern

// 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,
});

Inkrementelle Neuindizierung

// 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

Indizierungsstatus prüfen

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"]
// }

Unterstützte Sprachen

Programmiersprachen (über 35 Dateitypen):

• Web: TypeScript, JavaScript, Vue, Svelte

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

• Systeme: C, C++, C#

• Mobil: Swift, Kotlin, Dart

• Funktional: Scala, Clojure, Haskell, OCaml

• Skripting: Bash, Shell, Fish

• Daten: SQL, GraphQL, Protocol Buffers

• Konfiguration: JSON, YAML, TOML, XML, Markdown

Siehe Konfiguration für die vollständige Liste und Anpassungsoptionen.

Benutzerdefinierte Ignorier-Muster

Erstellen Sie eine .contextignore-Datei in Ihrem Projektstammverzeichnis, um zusätzliche Muster anzugeben, die ignoriert werden sollen:

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

Best Practices

1. Einmal indizieren, inkrementell aktualisieren: Verwenden Sie index_codebase für die erste Indizierung, dann reindex_changes für Aktualisierungen

2. Verwenden Sie Filter: Schränken Sie den Suchbereich mit fileTypes und pathPattern für bessere Ergebnisse ein

3. Aussagekräftige Abfragen: Verwenden Sie natürliche Sprache, die beschreibt, wonach Sie suchen (z. B. "Datenbankverbindungs-Pooling" statt "db")

4. Status zuerst prüfen: Verwenden Sie get_index_status, um zu überprüfen, ob eine Codebasis indiziert ist, bevor Sie suchen

5. Lokales Embedding: Verwenden Sie Ollama (Standard), um alles lokal und privat zu halten

Leistung

Typische Leistung auf einem modernen Laptop (Apple M1/M2 oder ähnlich):

Hinweis: Die Indizierungszeit variiert je nach Embedding-Anbieter. Ollama (lokal) ist am schnellsten für die erste Indizierung.

Git-Verlaufssuche

Indizieren und durchsuchen Sie den Git-Commit-Verlauf Ihres Repositories mit natürlicher Sprache. Perfekt, um vergangene Korrekturen zu finden, Änderungsmuster zu verstehen und aus früheren Arbeiten zu lernen.

Funktionen

• Semantische Commit-Suche: Finden Sie Commits, indem Sie in natürlicher Sprache beschreiben, wonach Sie suchen

• Klassifizierung konventioneller Commits: Automatische Klassifizierung von Commits (feat, fix, refactor, etc.)

• Inkrementelle Aktualisierungen: Indizieren Sie nur neue Commits für effiziente Aktualisierungen

• Umfangreiche Filterung: Filtern nach Commit-Typ, Autor oder Datumsbereich

• Metadatenextraktion: Enthält geänderte Dateien, Einfügungen/Löschungen und vollständigen Commit-Kontext

Schnellstart

1. Indizieren Sie den Git-Verlauf Ihres Repositories:

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

2. Suchen Sie nach relevanten Commits:

# 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. Halten Sie den Index auf dem neuesten Stand:

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

Anwendungsfälle

• **Ähn