Qdrant

offiziell

Implementieren Sie eine semantische Gedächtnisschicht auf Basis der Qdrant-Vektorsuchmaschine.

GitHub

1.5k

Was kann man mit Qdrant MCP machen?

Informationen als semantische Erinnerungen speichern — Text mit optionalen Metadaten mithilfe von qdrant-store in einer Qdrant-Sammlung speichern.
Relevante Erinnerungen anhand der Bedeutung finden — Gespeicherte Informationen mit natürlichsprachlichen Abfragen über qdrant-find durchsuchen.
Eine Standardsammlung konfigurieren — COLLECTION_NAME festlegen, damit die Speicher- und Suchwerkzeuge ohne erneute Angabe auf einer vordefinierten Sammlung arbeiten.
Im schreibgeschützten Modus ausführen — Das Werkzeug qdrant-store deaktivieren, indem QDRANT_READ_ONLY=true gesetzt wird, um nur das Abrufen zu erlauben.
Werkzeugbeschreibungen für spezifische Arbeitsabläufe anpassen — TOOL_STORE_DESCRIPTION und TOOL_FIND_DESCRIPTION überschreiben, um die KI zu einer domänenspezifischen Nutzung wie der Suche nach Codeausschnitten zu führen.

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 Werkzeugen ermöglicht. Ob Sie eine KI-gestützte IDE entwickeln, eine Chat-Schnittstelle erweitern oder benutzerdefinierte KI-Workflows erstellen – MCP bietet einen standardisierten Weg, LLMs mit dem benötigten Kontext zu verbinden.

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

Überblick

Ein offizieller Model Context Protocol-Server zum Speichern und Abrufen von Erinnerungen in der Qdrant-Vektorsuchmaschine. Er fungiert als semantische Speicherschicht oberhalb der Qdrant-Datenbank.

Komponenten

Werkzeuge

qdrant-store
- Speichert Informationen in der Qdrant-Datenbank
- Eingabe:
  - information (Zeichenkette): Zu speichernde Information
  - metadata (JSON): Optionale zu speichernde Metadaten
  - collection_name (Zeichenkette): Name der Collection, in der die Information gespeichert werden soll. Dieses Feld ist erforderlich, wenn kein Standard-Collection-Name existiert. Wenn ein Standard-Collection-Name existiert, ist dieses Feld nicht aktiviert.
- Rückgabe: Bestätigungsnachricht
qdrant-find
- Ruft relevante Informationen aus der Qdrant-Datenbank ab
- Eingabe:
  - query (Zeichenkette): Für die Suche zu verwendende Abfrage
  - collection_name (Zeichenkette): Name der Collection, in der die Information gespeichert werden soll. Dieses Feld ist erforderlich, wenn kein Standard-Collection-Name existiert. Wenn ein Standard-Collection-Name existiert, 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, das zur Auswahl des Transportprotokolls dient.

[!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-Collection.	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 Speicher-Werkzeug	Siehe Standard in `settings.py`
`TOOL_FIND_DESCRIPTION`	Benutzerdefinierte Beschreibung für das Such-Werkzeug	Siehe Standard in `settings.py`
`QDRANT_SEARCH_LIMIT`	Maximale Anzahl der von der Suche zurückzugebenden Ergebnisse	`10`
`QDRANT_READ_ONLY`	Aktiviert den Nur-Lese-Modus (deaktiviert das `qdrant-store`-Werkzeug)	`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`	Setzt das Logging-Level (DEBUG, INFO, WARNING, ERROR, CRITICAL)	`INFO`
`FASTMCP_SERVER_DEBUG`	Aktiviert den Debug-Modus	`false`
`FASTMCP_SERVER_HOST`	Host-Adresse, an die der Server gebunden wird	`127.0.0.1`
`FASTMCP_SERVER_PORT`	Port, auf dem der Server läuft	`8000`
`FASTMCP_SERVER_ON_DUPLICATE_RESOURCES`	Verhalten bei doppelten Ressourcen (warn, error, replace, ignore)	`warn`
`FASTMCP_SERVER_ON_DUPLICATE_TOOLS`	Verhalten bei doppelten Werkzeugen (warn, error, replace, ignore)	`warn`
`FASTMCP_SERVER_ON_DUPLICATE_PROMPTS`	Verhalten bei doppelten Prompts (warn, error, replace, ignore)	`warn`
`FASTMCP_SERVER_DEPENDENCIES`	Liste der in der Serverumgebung zu installierenden Abhängigkeiten	`[]`

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

Installation

Verwendung von uvx

Bei Verwendung von uvx ist keine spezifische 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 möglicherweise nur von lokalen MCP-Clients verwendet werden
sse: Server-Sent Events-Transport, perfekt für entfernte Clients
streamable-http: Streamable HTTP-Transport, perfekt für entfernte Clients, neuer als SSE

Der Standardtransport ist stdio, falls nicht anders angegeben.

Wenn der SSE-Transport verwendet wird, 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

Verwendung von Docker

Ein Dockerfile ist zum Bauen 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 notwendig, wenn der Server in einem Docker-Container ausgeführt wird.

Installation über Smithery

Um den Qdrant MCP Server für Claude Desktop automatisch über Smithery zu installieren:

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 Collection mit dem angegebenen Namen, falls diese nicht existiert.

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

Unterstützung für andere Werkzeuge

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 Code-Suchwerkzeug für Cursor oder Windsurf fungiert, indem Sie die Werkzeugbeschreibungen 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 entfernte Verbindungen unterstützt. Dies erleichtert die gemeinsame Nutzung des Servers im Team oder die Verwendung in einer Cloud-Umgebung.

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

Code-Snippets, Dokumentation und Implementierungsdetails speichern
Relevante Codebeispiele basierend auf semantischer Suche abrufen
Entwicklern helfen, bestimmte Implementierungen oder Nutzungsmuster zu finden

Sie können die Datenbank befüllen, indem Sie natürlichsprachliche Beschreibungen von Code-Snippets (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 Werkzeugbeschreibungen sind Beispiele und müssen möglicherweise für Ihren spezifischen Anwendungsfall angepasst werden. Erwägen Sie, die Beschreibungen anzupassen, um sie besser an den Workflow Ihres Teams und die spezifischen Arten von Code-Snippets anzupassen, die Sie speichern und abrufen möchten.

Wenn Sie den mcp-server-qdrant erfolgreich installiert haben, ihn aber immer noch nicht mit Cursor zum Laufen bringen, sollten Sie erwägen, die Cursor-Regeln zu erstellen, damit die MCP-Werkzeuge immer dann verwendet werden, wenn der Agent ein neues Code-Snippet produziert. Sie können die Regeln so einschränken, dass sie nur für bestimmte Dateitypen gelten, um die Verwendung des MCP-Servers für Dokumentation oder andere Inhaltstypen 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 eine 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
```

Verwendung der semantischen Codesuche in Claude Code

Werkzeugbeschreibungen, angegeben in TOOL_STORE_DESCRIPTION und TOOL_FIND_DESCRIPTION, 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. Jedoch sollte Claude Code bereits in der Lage sein:

Das qdrant-store-Werkzeug zu verwenden, um Code-Snippets mit Beschreibungen zu speichern.
Das qdrant-find-Werkzeug zu verwenden, um mit natürlicher Sprache nach relevanten Code-Snippets zu suchen.

MCP-Server im Entwicklungsmodus ausführen

Der MCP-Server kann im Entwicklungsmodus mit dem Befehl mcp dev ausgeführt werden. Dies startet den Server und öffnet den MCP- Inspector in Ihrem Browser.

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

Verwendung mit VS Code

Für eine Ein-Klick-Installation klicken Sie auf eine der Installationsschaltflächen unten:

Manuelle Installation

Fügen Sie den folgenden JSON-Block zu Ihrer Benutzereinstellungsdatei (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 eine .vscode/mcp.json-Datei in Ihrem Arbeitsbereich 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, eröffnen Sie ein Issue! Wir freuen uns über alle Beiträge.

`mcp-server-qdrant` lokal testen

Der MCP Inspector ist ein Entwicklerwerkzeug 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 Inspector zu verwenden.

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

Öffnen Sie nach dem Start Ihren Browser unter http://localhost:5173, um auf die Inspector-Oberfläche zuzugreifen.

Lizenz

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