Qdrant MCP

offiziell

Semantische Suche mit der Qdrant-Vektordatenbank.

Was kann man mit Qdrant MCP machen?

Nutze Qdrant als semantische Gedächtnisschicht für deinen KI-Assistenten, damit dieser Informationen nach Bedeutung statt nach exakten Schlüsselwörtern speichern und abrufen kann.

Semantische Erinnerungen speichern — Bitte deinen Assistenten, Informationen mit optionalen Metadaten über qdrant-store in Qdrant zu speichern, um sie später abzurufen.
Relevante Erinnerungen abrufen — Verwende qdrant-find, um gespeicherte Informationen mit einer natürlichsprachlichen Abfrage zu durchsuchen und passende Ergebnisse zu erhalten.
Eine Code-Snippet-Bibliothek aufbauen — Speichere Code-Snippets mit Beschreibungen und rufe sie semantisch ab, wie in den Cursor- und Claude-Code-Setups gezeigt.
Bestimmte Sammlungen ansprechen — Speichere oder suche in einer benannten Sammlung über collection_name oder verlasse dich auf die Standardeinstellung, die durch COLLECTION_NAME festgelegt ist.

Dokumentation

mcp-server-qdrant: Ein Qdrant-MCP-Server

Das Model Context Protocol (MCP) ist ein offenes Protokoll, das eine nahtlose Integration zwischen LLM-Anwendungen und externen Datenquellen und Tools ermöglicht. Ob Sie eine KI-gestützte IDE entwickeln, eine Chat-Oberfläche verbessern oder benutzerdefinierte KI-Workflows erstellen, MCP bietet einen standardisierten Weg, LLMs mit dem Kontext zu verbinden, den sie benötigen.

Dieses Repository ist ein Beispiel dafür, wie man einen MCP-Server für Qdrant, eine Vektor-Suchmaschine, erstellt.

Überblick

Ein offizieller Model-Context-Protocol-Server zum Speichern und Abrufen von Erinnerungen in der Qdrant-Vektor-Suchmaschine. Er fungiert als semantische Gedächtnisschicht über der Qdrant-Datenbank.

Komponenten

Tools

qdrant-store
- Speichert Informationen in der Qdrant-Datenbank
- Eingabe:
  - information (Zeichenfolge): Zu speichernde Informationen
  - metadata (JSON): Optionale Metadaten zum Speichern
  - collection_name (Zeichenfolge): Name der Sammlung, in der die Informationen gespeichert werden sollen. Dieses Feld ist erforderlich, wenn es keinen Standard-Sammlungsnamen gibt. Wenn es einen Standard-Sammlungsnamen gibt, ist dieses Feld nicht aktiviert.
- Rückgabe: Bestätigungsmeldung
qdrant-find
- Ruft relevante Informationen aus der Qdrant-Datenbank ab
- Eingabe:
  - query (Zeichenfolge): Abfrage für die Suche
  - collection_name (Zeichenfolge): Name der Sammlung, in der die Informationen gespeichert werden sollen. Dieses Feld ist erforderlich, wenn es keinen Standard-Sammlungsnamen gibt. Wenn es einen Standard-Sammlungsnamen gibt, ist dieses Feld nicht aktiviert.
- Rückgabe: In der Qdrant-Datenbank gespeicherte Informationen als separate Nachrichten

Umgebungsvariablen

Die Konfiguration erfolgt über Umgebungsvariablen. Das einzige Befehlszeilenargument ist --transport, mit dem das Transportprotokoll ausgewählt wird.

[!NOTE] Sie können nicht gleichzeitig QDRANT_URL und QDRANT_LOCAL_PATH angeben.

Name	Beschreibung	Standardwert
`QDRANT_URL`	URL des Qdrant-Servers	Keine
`QDRANT_API_KEY`	API-Schlüssel für den Qdrant-Server	Keine
`COLLECTION_NAME`	Name der zu verwendenden Standard-Sammlung.	Keine
`QDRANT_LOCAL_PATH`	Pfad zur lokalen Qdrant-Datenbank (Alternative zu `QDRANT_URL`)	Keine
`EMBEDDING_PROVIDER`	Zu verwendender Embedding-Anbieter (derzeit wird nur „fastembed“ unterstützt)	`fastembed`
`EMBEDDING_MODEL`	Name des zu verwendenden Embedding-Modells	`sentence-transformers/all-MiniLM-L6-v2`
`TOOL_STORE_DESCRIPTION`	Benutzerdefinierte Beschreibung für das Store-Tool	Siehe Standard in `settings.py`
`TOOL_FIND_DESCRIPTION`	Benutzerdefinierte Beschreibung für das Find-Tool	Siehe Standard in `settings.py`
`QDRANT_SEARCH_LIMIT`	Maximale Anzahl der von der Suche zurückzugebenden Ergebnisse	`10`
`QDRANT_READ_ONLY`	Schreibgeschützten Modus aktivieren (deaktiviert das `qdrant-store`-Tool)	`false`

FastMCP-Umgebungsvariablen

Da mcp-server-qdrant auf FastMCP basiert, werden auch alle FastMCP-Umgebungsvariablen unterstützt. Die wichtigsten sind unten aufgeführt:

Umgebungsvariable	Beschreibung	Standardwert
`FASTMCP_LOG_LEVEL`	Protokollierungsebene festlegen (DEBUG, INFO, WARNING, ERROR, CRITICAL)	`INFO`
`FASTMCP_SERVER_DEBUG`	Debug-Modus aktivieren	`false`
`FASTMCP_SERVER_HOST`	Host-Adresse, an die der Server gebunden werden soll	`127.0.0.1`
`FASTMCP_SERVER_PORT`	Port, auf dem der Server laufen soll	`8000`
`FASTMCP_SERVER_ON_DUPLICATE_RESOURCES`	Verhalten bei doppelten Ressourcen (warn, error, replace, ignore)	`warn`
`FASTMCP_SERVER_ON_DUPLICATE_TOOLS`	Verhalten bei doppelten Tools (warn, error, replace, ignore)	`warn`
`FASTMCP_SERVER_ON_DUPLICATE_PROMPTS`	Verhalten bei doppelten Prompts (warn, error, replace, ignore)	`warn`
`FASTMCP_SERVER_DEPENDENCIES`	Liste der im Server-Umfeld zu installierenden Abhängigkeiten	`[]`

[!NOTE] Serverspezifische Einstellungen verwenden das Präfix FASTMCP_SERVER_. Dies kann sich in zukünftigen Versionen ändern.

Installation

Mit uvx

Bei Verwendung von uvx ist keine spezielle Installation erforderlich, um mcp-server-qdrant direkt auszuführen.

QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
EMBEDDING_MODEL="sentence-transformers/all-MiniLM-L6-v2" \
uvx mcp-server-qdrant

Transportprotokolle

Der Server unterstützt verschiedene Transportprotokolle, die mit dem Flag --transport angegeben werden können:

QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
uvx mcp-server-qdrant --transport sse

Unterstützte Transportprotokolle:

stdio (Standard): Standard-Eingabe-/Ausgabe-Transport, kann nur von lokalen MCP-Clients verwendet werden
sse: Server-Sent-Events-Transport, perfekt für Remote-Clients
streamable-http: Streamable-HTTP-Transport, perfekt für Remote-Clients, neuer als SSE

Der Standardtransport ist stdio, wenn nichts anderes angegeben ist.

Bei Verwendung des SSE-Transports lauscht der Server auf dem angegebenen Port und wartet auf eingehende Verbindungen. Der Standardport ist 8000, kann jedoch über die Umgebungsvariable FASTMCP_SERVER_PORT geändert werden.

QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
FASTMCP_SERVER_PORT=1234 \
uvx mcp-server-qdrant --transport sse

Mit Docker

Ein Dockerfile ist zum Erstellen und Ausführen des MCP-Servers verfügbar:

# 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] Bitte beachten Sie, dass wir FASTMCP_SERVER_HOST="0.0.0.0" setzen, damit der Server auf allen Netzwerkschnittstellen lauscht. Dies ist erforderlich, wenn der Server in einem Docker-Container ausgeführt wird.

Installation über Smithery

So installieren Sie den Qdrant-MCP-Server für Claude Desktop automatisch über Smithery:

npx @smithery/cli install mcp-server-qdrant --client claude

Manuelle Konfiguration von Claude Desktop

Um diesen Server mit der Claude-Desktop-App zu verwenden, fügen Sie die folgende Konfiguration zum Abschnitt „mcpServers“ Ihrer claude_desktop_config.json hinzu:

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

Für den lokalen Qdrant-Modus:

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

Dieser MCP-Server erstellt automatisch eine Sammlung mit dem angegebenen Namen, falls sie nicht existiert.

Standardmäßig verwendet der Server das Embedding-Modell sentence-transformers/all-MiniLM-L6-v2 zum Kodieren von Erinnerungen. Derzeit werden nur FastEmbed-Modelle unterstützt.

Unterstützung für andere Tools

Dieser MCP-Server kann mit jedem MCP-kompatiblen Client verwendet werden. Sie können ihn beispielsweise mit Cursor und VS Code verwenden, die integrierte Unterstützung für das Model Context Protocol bieten.

Verwendung mit Cursor/Windsurf

Sie können diesen MCP-Server so konfigurieren, dass er als Codesuchtool für Cursor oder Windsurf funktioniert, indem Sie die Tool- Beschreibungen anpassen:

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

In Cursor/Windsurf können Sie den MCP-Server dann in Ihren Einstellungen konfigurieren, indem Sie auf diesen laufenden Server über das SSE-Transportprotokoll verweisen. Die Beschreibung zum Hinzufügen eines MCP-Servers zu Cursor finden Sie in der Cursor- Dokumentation. Wenn Sie Cursor/Windsurf lokal ausführen, können Sie die folgende URL verwenden:

http://localhost:8000/sse

[!TIP] Wir empfehlen den SSE-Transport als bevorzugte Methode, um Cursor/Windsurf mit dem MCP-Server zu verbinden, da er Remote- Verbindungen unterstützt. So lässt sich der Server problemlos mit Ihrem Team teilen oder in einer Cloud-Umgebung verwenden.

Diese Konfiguration verwandelt den Qdrant-MCP-Server in ein spezialisiertes Codesuchtool, das Folgendes kann:

Codeausschnitte, Dokumentation und Implementierungsdetails speichern
Relevante Codebeispiele basierend auf semantischer Suche abrufen
Entwicklern helfen, bestimmte Implementierungen oder Verwendungsmuster zu finden

Sie können die Datenbank befüllen, indem Sie natürlichsprachliche Beschreibungen von Codeausschnitten (im Parameter information) zusammen mit dem eigentlichen Code (in der Eigenschaft metadata.code) speichern und dann mit natürlichsprachlichen Abfragen danach suchen, die beschreiben, wonach Sie suchen.

[!NOTE] Die oben bereitgestellten Tool-Beschreibungen sind Beispiele und müssen möglicherweise für Ihren spezifischen Anwendungsfall angepasst werden. Erwägen Sie, die Beschreibungen besser an den Workflow Ihres Teams und die spezifischen Arten von Codeausschnitten anzupassen, die Sie speichern und abrufen möchten.

Wenn Sie den mcp-server-qdrant erfolgreich installiert haben, aber dennoch nicht mit Cursor zum Laufen bringen können, erwägen Sie bitte, die Cursor-Regeln zu erstellen, damit die MCP-Tools immer verwendet werden, wenn der Agent einen neuen Codeausschnitt erstellt. Sie können die Regeln so einschränken, dass sie nur für bestimmte Dateitypen gelten, um die Verwendung des MCP-Servers für die Dokumentation oder andere Arten von Inhalten zu vermeiden.

Verwendung mit Claude Code

Sie können die Fähigkeiten von Claude Code erweitern, indem Sie es mit diesem MCP-Server verbinden und so semantische Suche über Ihre bestehende Codebasis ermöglichen.

Einrichten von mcp-server-qdrant

Fügen Sie den MCP-Server zu Claude Code hinzu:

# 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

Überprüfen Sie, ob der Server hinzugefügt wurde:
```
claude mcp list
```

Verwenden der semantischen Codesuche in Claude Code

Tool-Beschreibungen, die in TOOL_STORE_DESCRIPTION und TOOL_FIND_DESCRIPTION angegeben sind, leiten Claude Code bei der Verwendung des MCP-Servers an. Die oben bereitgestellten sind Beispiele und müssen möglicherweise für Ihren spezifischen Anwendungsfall angepasst werden. Allerdings sollte Claude Code bereits in der Lage sein:

Verwenden Sie das qdrant-store-Tool, um Codeausschnitte mit Beschreibungen zu speichern.
Verwenden Sie das qdrant-find-Tool, um mit natürlicher Sprache nach relevanten Codeausschnitten zu suchen.

MCP-Server im Entwicklungsmodus ausführen

Der MCP-Server kann mit dem Befehl mcp dev im Entwicklungsmodus ausgeführt werden. Dadurch wird der Server gestartet und der MCP- Inspektor in Ihrem Browser geöffnet.

COLLECTION_NAME=mcp-dev fastmcp dev src/mcp_server_qdrant/server.py

Verwendung mit VS Code

Für die Installation mit einem Klick klicken Sie auf eine der Installationsschaltflächen unten:

Manuelle Installation

Fügen Sie den folgenden JSON-Block zu Ihrer Datei „User Settings (JSON)“ in VS Code hinzu. Sie können dies tun, indem Sie Ctrl + Shift + P drücken und Preferences: Open User Settings (JSON) eingeben.

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

Oder wenn Sie Docker bevorzugen, fügen Sie stattdessen diese Konfiguration hinzu:

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

Alternativ können Sie in Ihrem Arbeitsbereich eine Datei .vscode/mcp.json mit folgendem Inhalt erstellen:

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

Für die Arbeitsbereichskonfiguration mit Docker verwenden Sie dies in .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}"
      }
    }
  }
}

Mitwirken

Wenn Sie Vorschläge haben, wie mcp-server-qdrant verbessert werden könnte, oder einen Fehler melden möchten, erstellen Sie ein Issue! Wir freuen uns über alle Beiträge.

Testen von `mcp-server-qdrant` lokal

Der MCP-Inspektor ist ein Entwicklertool zum Testen und Debuggen von MCP- Servern. Er führt sowohl eine Client-Benutzeroberfläche (Standardport 5173) als auch einen MCP-Proxy-Server (Standardport 3000) aus. Öffnen Sie die Client-Benutzeroberfläche in Ihrem Browser, um den Inspektor zu verwenden.

QDRANT_URL=":memory:" COLLECTION_NAME="test" \
fastmcp dev src/mcp_server_qdrant/server.py

Nach dem Start öffnen Sie Ihren Browser unter http://localhost:5173, um auf die Inspektor-Oberfläche zuzugreifen.

Lizenz

Dieser MCP-Server ist unter der Apache-Lizenz 2.0 lizenziert. Das bedeutet, dass Sie die Software frei verwenden, modifizieren und verbreiten können, vorbehaltlich der Bedingungen der Apache-Lizenz 2.0. Weitere Einzelheiten finden Sie in der LICENSE-Datei im Projekt-Repository.