qdrant-mcp-ollama

Ein Model Context Protocol (MCP)-Server für die Qdrant-Vektordatenbank, der Ollama für GPU-beschleunigte Embeddings verwendet.

Warum nicht das offizielle mcp-server-qdrant?

Der offizielle Qdrant-MCP-Server verwendet FastEmbed für Embeddings, was:

• Nur auf der CPU läuft – langsam bei großen Codebasen, moderne GPUs werden nicht ausgenutzt

• Ein anderes Modell verwendet (all-MiniLM-L6-v2, 384-dim) – leistungsfähigere Embeddings sind nicht möglich

• Im lokalen Modus eine Einzelprozess-/Single-Process-Sperre – nur ein MCP-Client kann gleichzeitig auf die Datenbank zugreifen

Dieser Server behebt alle drei Probleme:

Related MCP server: Claude Context MCP

Architektur

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

Voraussetzungen

• Ollama – installiert und läuft, ein Embedding-Modell ist heruntergeladen

• Docker – muss eingerichtet (läuft), um den Qdrant-Server zu betreiben

• uv – Python-Paketmanager (empfohlen) oder pip

Schnellstart

1. Ein Ollama-Embedding-Modell herunterladen

ollama pull bge-m3

2. Qdrant-Server starten

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

3. MCP-Start up

# 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. Codebasis einbetten

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

5. In deinem MCP-Client suchen

Nach der Konfiguration (siehe Abschnitte unten) frage deinen KI-Assistenten:

„Durchsuche die Codebasis nach Authentifizierungslogik.

Er nutzt das qdrant_' 'формулирует" – actually I'm about to write "Er nutzt das qdrant_find-Tool, um semantisch relevante Codeanteile zurückzugeben."

So:

„Durchsuche die Codebasis nach Authentifizierungslogik."

S**Fnd-Tool liefert dann semantisch relevante Code-Ausschnitte zurück.

Qdrant-Server einrichten

Option A: Docker (empfohlen)

Speichere Daten auf einem bestimmten Laufwerk (z. B. E: unter 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

Unter 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

Das restart unless-stopped-Flag sorgt dafür, dass Qdrant automatisch mit Docker Desktop startet.

Überprüfen, dass Qdrant läuft:

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

Option B: Qdrant Cloud

Registrieren bei cloud.qdrant.io und URL sowie API-Schlüssel notieren. Dann setzen:

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

Hinweis: Die Umgebungsvariable QDRANT_API_KEY wird automatisch an den Qdrant-Client durchgereicht.

Codebasis einbetten

Das Skript embed_codebase.py durchsucht ein Verzeichnis, zerlegt Quelldateien in Chunks und bettet sie über Ollama auf der GPU in Qdrant ein.

Grundlegende Verwendung

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

Mit Erweiterungs-Presets

# 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

Eigene Datei-Erweiterungen

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

Verfügbare Presets

Werden weder --preset noch --extensions angegeben, erkennt das Skript die Dateitypen automatisch.

Alle Optionen

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

Append-Modus

Standardmäßig ersetzt ein erneuter Skriptlauf die Collection. Mit --append wird an eine bestehende Collection angehängt:

# 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

Mehrere Codebasen verwenden

Verwende getrennte Collections für jede Codebasis, um die Suchergebnisse klar umgrenzt und relevant zu halten:

# 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

Bei der Konfiguration des MCP-Servers:

• Ohne COLLECTION_NAME: Du musst die Collection pro Anfrage angeben. Das ist ideal, wenn ein MCP-Server mehrere Projekte bedient.

• Mit COLLECTION_NAME: Eine Standard-Collection wird automatisch verwendet. Setze diesen Wert pro Projekt, wenn dein MCP-Client eine Projekt-spezifische Konfiguration unterstützt.

Claude Code konfigurieren

MCP-Server hinzufügen

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

Ersetze /path/to/qdrant-mcp-ollama/ durch den tatsächlichen Pfad, in den du dieses Repository geklont hast.

Mit einem Standard-Collectionnamen

Wenn du hauptsächlich an einem Projekt arbeitest:

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

Verifizieren

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

claude mcp get qdrant
# Shows full configuration details

Verwendung in Claude Code

Nach der Konfiguration kann Claude Code diese Tools nutzen:

• qdrant_store – Informationen speichern: „Speichere dieses Authentifizierungsmuster in Qdrant“

• qdrant_find – Suchen: „Finde Code zu Datenbank-kautionen“

Für Setups mit mehreren Collections (ohne COLLECTION_NAME), definiere die Collection in der Abfrage:

„Durchsuche die api-server-Collection nach Rate-Limiting-Logic“

Konfiguration von Kilo Code (VS-Code Extension)

Kilo Code ist eine VS-Code-Erweiterung with integrierter MCP-Unterstützung.

Option 1: Manuelle MCP-Konfiguration

1. Öffne die Kilo-Code-Einstellungen in VS Code

2. Wechsle zur MCP-Server-Konfiguration

3. Füge einen neuen Server hinzu:

4. Umgebungsvariablen setzen:

Option 2: VS-Code settings.json

Füge in den VS-Code settings.json (Ctrl+Shift+P > Einstellungen: Benutzer-Einstellungen (JSON) öffnen) hinzu:

{
  "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"
      }
    }
  }
}

Projektspezifisches Setup in Kilo Code

Für Multi-Codebase-Setups konfiguriere Kilo Code unter **projekt** (nicht global) mit einer projektbezogenen COLLECTION_NAME`. So durchsucht jedes Workspace nur seine eigene Codebasis.

Andere MCP-Clients Konfigurieren

Cursor / Windsurf

Führe den Server mit SSE-Transport aus, damit Remote-fähige Clients ihn erreichen können:

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

Stelle dann in den MCP-Einstellungen von Cursor/Windsurf die Verbindung her: http://localhost:8000/sse

Allgemeiner MCP-Client (stdio)

Der Standard-Transport ist stdio. Jeder MCP-Client, der stdio unterstützt, kann den Server wie folgt nutzen:

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

Konfigurationsreferenz

Umgebungsvariablen des MCP-Servers

Auswahl eines Embedding-Modells

Alle Modelle unten sind verfügbar über ollama pull <Model>:

Empfehlung: Beginne mit bge-m3. Es verarbeitet Code gut, unterstützt mehrsprachige Inhalte (Kommentare in jeder Sprache) und balanciert Qualität mit Geschwindigkeit.

Wichtig: Das Embedding-Modell, mit dem sie installiert wurde, muss mit dem Modell für die Suche übereinstimmen. Wenn du ein anderes Modell zum erneuten Einbetten verwendest, wollte ich die Collection wiederherstellen.

GPU-Auslastung

Größere Modelle belegen mehr GPU. Falls deine GPU nicht vollständig ausgelastet wird:

• Wechsle von nomic-embed-text (274 MB) zu bge-m3 (1.2 GB) oder einem größeren Modell

• Das Einbettungsskript sendet alle Texte in einem einzelnen Batch, um die GPU-Sättigung (Auslastung g) zu maximieren

• Bei einzelnen Abfragen (z. B. qdrant_find) sind kurze GPU-Ausschläge normal – das Einbetten einer einzelnen Abfrage SomeTime ist Millisekunden nötig

GPU-Auslastung prüfen: nvidia-smi (NVIDIA) oder rocm-smi (AMD)

MCP-Tools

qdrant_store

Speichert Informationen in der Qdrant-Datenbank.

qdrant_find

Sucht mit semantischer Ähnlichkeit nach relevanten Informationen.

Fehlerbehebung – troubleshooting

„Connection closed“ / MCP-Connection server won't start

• Läuft Ollama? Überprüfe mit ollama list. Falls erforderlich starten mit ollama serve.

• Ist das Embedding-Modell geladen? Einf ollama pull bge-m3`.

• Läuft Qdrant? Prüfe mit docker ps --filter name=qdrant-server.

„Collection existiert nicht“

Die COLLECTION wird beim Einbetten oder beim ersten qdrant_store-Aufruf erzeugt. Du hast zwei Optionen:

• embed_code.py ausführen, um die Sammlung zu indizieren

• Oder mit qdrant_store einen Eintrag speichern, um die Collection automatisch und zu herzustellen

Dimension-mismatch ``-Fehler

Dies tritt auf, wenn die Collection mit einem Modell erstellt wurde, aber die Abfrage mit einem anderen Embedding-Modell durchgeführt wird.

• Lösungsziele:

  1. Collection löschen: Besuche http://localhost:6333/dashboard

  2. Mit dem richtigen Modell neu einbetten

  3. Stelle sicher, dass EMBEDDING_MODEL in der MCP-Serverkonfiguration mit dem verwendeten Einbetmodel übereinstimmt.

„Storage folder is already accessed by another instance“

Das ist der Fehler vom offiziellen mcp-server-qdrant Modus – verwendet wird ein lokaler Speicherpfad (QDRANT_LOCAL_PATH). Dieses Projekt umgeht situ용 durch die Verbindung über eine URL zur Qdrant-Server-instanz. Stelle sicher, dass nicht beide Server auf denselben lokalen Pfad gelenkt werden.

Langsame Einbettungen / Geringe GPU-Auslastung

Höheres GPU-ModellGenisch:

• Siehe Wahl des Embedding-Modell-Abschnittss oben.

• Verwende ein größeres Modell: bge-m3 (1,2 GB) statt nomic-embed-text (274 MB)

• Das Embedding-Skript sendet alle Texte in einem Batch — wenn du Tausende von Chunks hast, maximiert das die GPU-Auslastung

• Bei sehr großen Codebasen (10.000+ Dateien) solltest du erwägen, die Verarbeitung in mehrere Durchläufe pro Verzeichnis aufzuteilen

Lizenz

Apache License 2.0 — siehe LICENSE.