Qdrant

offiziell

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

GitHub

1.5k

Was kann man mit Qdrant MCP machen?

Speicherfunktionen — Bitten Sie Ihren Assistenten, Informationen mit qdrant-store zu speichern, optional mit Metadaten und gezielt auf eine bestimmte Sammlung.
Semantische Suche — Verwenden Sie qdrant-find, um relevante gespeicherte Informationen per natürlichsprachlicher Abfrage abzurufen, wobei die Ergebnisse durch QDRANT_SEARCH_LIMIT begrenzt werden.
Code-Snippet-Verwaltung — Konfigurieren Sie Tool-Beschreibungen, um Code mit Metadaten zu speichern und ihn über semantische Suche zur Wiederverwendung in Cursor oder Claude Code abzurufen.
Nur-Lese-Modus — Aktivieren Sie QDRANT_READ_ONLY, um qdrant-store zu deaktivieren und nur Suchoperationen zuzulassen.

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 benötigten Kontext zu verbinden.

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

Überblick

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

Komponenten

Tools

qdrant-store
- Speichert einige Informationen in der Qdrant-Datenbank
- Eingabe:
  - information (String): Zu speichernde Informationen
  - metadata (JSON): Optionale Metadaten zum Speichern
  - collection_name (String): Name der Sammlung, in der die Informationen gespeichert werden sollen. Dieses Feld ist erforderlich, wenn es keinen Standard-Sammlungsnamen gibt. Wenn ein Standard-Sammlungsname vorhanden ist, ist dieses Feld nicht aktiviert.
- Rückgabe: Bestätigungsmeldung
qdrant-find
- Ruft relevante Informationen aus der Qdrant-Datenbank ab
- Eingabe:
  - query (String): Abfrage für die Suche
  - collection_name (String): Name der Sammlung, in der die Informationen gespeichert werden sollen. Dieses Feld ist erforderlich, wenn es keinen Standard-Sammlungsnamen gibt. Wenn ein Standard-Sammlungsname vorhanden ist, 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 verwendet 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 Standardsammlung.	Keine
`QDRANT_LOCAL_PATH`	Pfad zur lokalen Qdrant-Datenbank (Alternative zu `QDRANT_URL`)	Keine
`EMBEDDING_PROVIDER`	Zu verwendender Embedding-Anbieter (aktuell 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`	Protokollierungsstufe festlegen (DEBUG, INFO, WARNING, ERROR, CRITICAL)	`INFO`
`FASTMCP_SERVER_DEBUG`	Debug-Modus aktivieren	`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 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 Abhängigkeiten, die in der Serverumgebung installiert werden sollen	`[]`

[!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 über das 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-Input/Output-Transport, wird möglicherweise nur von lokalen MCP-Clients verwendet
sse: Server-Sent-Events-Transport, ideal für entfernte Clients
streamable-http: Streamable-HTTP-Transport, ideal für entfernte Clients, neuer als SSE

Der Standardtransport ist stdio, sofern 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

Mit Docker

Eine 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 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 Sammlung mit dem angegebenen Namen, falls sie nicht existiert.

Standardmäßig verwendet der Server das sentence-transformers/all-MiniLM-L6-v2-Embedding-Modell, um Erinnerungen zu codieren. 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 als Code-Suchtool für Cursor oder Windsurf konfigurieren, indem Sie die Toolbeschreibungen 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 mit dem SSE-Transportprotokoll verweisen. Die Beschreibung zum Hinzufügen eines MCP-Servers zu Cursor finden Sie in der https://docs.cursor.com/context/model-context-protocol#adding-an-mcp-server-to-cursor. 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 zum Verbinden von Cursor/Windsurf mit dem MCP-Server, da dieser Fernverbindungen unterstützt. Dadurch lässt sich der Server problemlos mit Ihrem Team teilen oder in einer Cloud-Umgebung verwenden.

Diese Konfiguration wandelt den Qdrant-MCP-Server in ein spezialisiertes Code-Suchtool um, das Folgendes kann:

Code-Ausschnitte, 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 Code-Ausschnitten (im information-Parameter) zusammen mit dem eigentlichen Code (in der metadata.code-Eigenschaft) speichern und dann mithilfe natürlichsprachlicher Abfragen danach suchen, die beschreiben, wonach Sie suchen.

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

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

Verwendung mit Claude Code

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

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

Semantische Codesuche in Claude Code verwenden

Toolbeschreibungen, 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:

Das qdrant-store-Tool zum Speichern von Code-Ausschnitten mit Beschreibungen zu verwenden.
Das qdrant-find-Tool zum Durchsuchen relevanter Code-Ausschnitte mithilfe natürlicher Sprache zu verwenden.

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 Ein-Klick-Installation 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.

`mcp-server-qdrant` lokal testen

Der MCP-Inspektor ist ein Entwicklertool zum Testen und Debuggen von MCP-Servern. Er führt sowohl eine Client-Oberfläche (Standardport 5173) als auch einen MCP-Proxy-Server (Standardport 3000) aus. Öffnen Sie die Client-Oberflä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 verteilen dürfen, vorbehaltlich der Bedingungen der Apache-Lizenz 2.0. Weitere Einzelheiten finden Sie in der LICENSE-Datei im Projekt-Repository.