Qdrant MCP

offiziell

Semantische Suche mit der Qdrant-Vektordatenbank.

Was kann man mit Qdrant MCP machen?

  • Erinnerungen speichern — Bitte deinen Assistenten, Informationen mit optionalen Metadaten mithilfe von qdrant-store in einer Qdrant-Sammlung zu speichern.
  • Semantische Suche — Rufe relevante gespeicherte Informationen mit einer natürlichsprachlichen query über qdrant-find ab.
  • Sammlung auswählen — Gib pro Aufruf eine bestimmte collection_name an oder lege über COLLECTION_NAME eine Standardsammlung fest.
  • Tool-Beschreibungen anpassen — Passe TOOL_STORE_DESCRIPTION und TOOL_FIND_DESCRIPTION an, um den Server in ein Such-Tool für Code-Snippets zu verwandeln.
  • Schreibgeschützter Modus — Aktiviere QDRANT_READ_ONLY, um das Speichern zu deaktivieren und nur den Abruf zu erlauben.
  • Ergebnisse abstimmen — Begrenze die Suchergebnisse mit QDRANT_SEARCH_LIMIT und wähle über EMBEDDING_MODEL ein Embedding-Modell aus.

Dokumentation

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

smithery badge

Das Model Context Protocol (MCP) ist ein offenes Protokoll, das eine nahtlose Integration zwischen LLM-Anwendungen und externen Datenquellen und Tools ermöglicht. Ganz gleich, ob Sie eine KI-gestützte IDE entwickeln, eine Chat-Oberfläche erweitern oder benutzerdefinierte KI-Workflows erstellen: MCP bietet eine standardisierte Möglichkeit, LLMs mit dem benötigten Kontext zu verbinden.

Dieses Repository zeigt beispielhaft, wie ein MCP-Server für Qdrant, eine Vektorsuchmaschine, erstellt wird.

Übersicht

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

Komponenten

Tools

  1. qdrant-store
    • Informationen in der Qdrant-Datenbank speichern
    • Eingabe:
      • information (string): Zu speichernde Informationen
      • metadata (JSON): Optionale Metadaten zum Speichern
      • collection_name (string): Name der Collection, in der die Informationen gespeichert werden sollen. Dieses Feld ist erforderlich, wenn kein Standard-Collection-Name festgelegt ist. Wenn ein Standard-Collection-Name festgelegt ist, ist dieses Feld nicht aktiviert.
    • Rückgabe: Bestätigungsnachricht
  2. qdrant-find
    • Relevante Informationen aus der Qdrant-Datenbank abrufen
    • Eingabe:
      • query (string): Für die Suche zu verwendende Abfrage
      • collection_name (string): Name der Collection, in der die Informationen gespeichert werden sollen. Dieses Feld ist erforderlich, wenn kein Standard-Collection-Name festgelegt ist. Wenn ein Standard-Collection-Name festgelegt 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, mit dem das Transportprotokoll ausgewählt wird.

[!NOTE] QDRANT_URL und QDRANT_LOCAL_PATH können nicht gleichzeitig angegeben werden.

NameBeschreibungStandardwert
QDRANT_URLURL des Qdrant-ServersNone
QDRANT_API_KEYAPI-Schlüssel für den Qdrant-ServerNone
COLLECTION_NAMEName der zu verwendenden Standard-Collection.None
QDRANT_LOCAL_PATHPfad zur lokalen Qdrant-Datenbank (Alternative zu QDRANT_URL)None
EMBEDDING_PROVIDERZu verwendender Embedding-Anbieter (derzeit wird nur „fastembed“ unterstützt)fastembed
EMBEDDING_MODELName des zu verwendenden Embedding-Modellssentence-transformers/all-MiniLM-L6-v2
TOOL_STORE_DESCRIPTIONBenutzerdefinierte Beschreibung für das Store-ToolSiehe Standardwert in settings.py
TOOL_FIND_DESCRIPTIONBenutzerdefinierte Beschreibung für das Find-ToolSiehe Standardwert in settings.py
QDRANT_SEARCH_LIMITMaximale Anzahl der Suchergebnisse10
QDRANT_READ_ONLYSchreibgeschützten Modus aktivieren (deaktiviert das Tool qdrant-store)false

FastMCP-Umgebungsvariablen

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

UmgebungsvariableBeschreibungStandardwert
FASTMCP_LOG_LEVELProtokollierungsstufe festlegen (DEBUG, INFO, WARNING, ERROR, CRITICAL)INFO
FASTMCP_DEBUGDebug-Modus aktivierenfalse
FASTMCP_HOSTHostadresse, an die der Server gebunden wird (SSE- und HTTP-Transporte)127.0.0.1
FASTMCP_PORTPort, auf dem der Server ausgeführt wird (SSE- und HTTP-Transporte)8000
FASTMCP_MASK_ERROR_DETAILSAusnahmedetails in Tool-Fehlermeldungen an Clients ausblendenfalse

[!NOTE] Vor Version 0.9.0 verwendeten diese Einstellungen das Präfix FASTMCP_SERVER_, zum Beispiel FASTMCP_SERVER_HOST. Die alten Namen FASTMCP_SERVER_HOST, FASTMCP_SERVER_PORT und FASTMCP_SERVER_DEBUG funktionieren weiterhin, sind jedoch veraltet und werden in einer zukünftigen Version entfernt. Wenn beide Namen festgelegt sind, hat der neue Vorrang.

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): Standardein-/ausgabe-Transport, möglicherweise nur für lokale MCP-Clients geeignet
  • sse: Server-Sent-Events-Transport, ideal für Remote-Clients
  • streamable-http: Streamable-HTTP-Transport, ideal für Remote-Clients und neuer als SSE

Wenn kein Transport angegeben ist, wird standardmäßig stdio verwendet.

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

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

Mit Docker

Zum Erstellen und Ausführen des MCP-Servers steht eine Dockerfile zur Verfügung:

# Build the container
docker build -t mcp-server-qdrant .

# Run the container
docker run -p 8000:8000 \
  -e FASTMCP_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] Beachten Sie, dass wir FASTMCP_HOST="0.0.0.0" festlegen, damit der Server an 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 automatisch für Claude Desktop ü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 Collection mit dem angegebenen Namen, falls sie noch 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 Tools

Dieser MCP-Server kann mit jedem MCP-kompatiblen Client verwendet werden. Beispielsweise können Sie ihn 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

Anschließend können Sie den MCP-Server in Cursor/Windsurf in den Einstellungen konfigurieren, indem Sie über das SSE-Transportprotokoll auf diesen laufenden Server verweisen. Eine Anleitung 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 SSE als bevorzugte Verbindungsmethode zwischen Cursor/Windsurf und dem MCP-Server, da damit Remote- Verbindungen unterstützt werden. So lässt sich der Server einfach mit Ihrem Team teilen oder in einer Cloud-Umgebung verwenden.

Diese Konfiguration verwandelt den Qdrant-MCP-Server in ein spezialisiertes Code-Suchtool, mit dem Sie:

  1. Codeausschnitte, Dokumentation und Implementierungsdetails speichern können
  2. Relevante Codebeispiele anhand einer semantischen Suche abrufen können
  3. Entwicklern helfen können, bestimmte Implementierungen oder Verwendungsmuster zu finden

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

[!NOTE] Die oben angegebenen Toolbeschreibungen sind Beispiele und müssen möglicherweise an Ihren konkreten Anwendungsfall angepasst werden. Erwägen Sie, die Beschreibungen so anzupassen, dass sie besser zum Workflow Ihres Teams und zu den spezifischen Arten von Codeausschnitten passen, die Sie speichern und abrufen möchten.

Wenn Sie den mcp-server-qdrant erfolgreich installiert haben, ihn aber trotzdem nicht mit Cursor zum Laufen bringen, sollten Sie Cursor-Regeln erstellen, damit die MCP-Tools immer verwendet werden, wenn der Agent einen neuen Codeausschnitt erstellt. Sie können die Regeln auf bestimmte Dateitypen beschränken, um zu vermeiden, dass der MCP-Server für Dokumentation oder andere Arten von Inhalten verwendet wird.

Verwendung mit Claude Code

Sie können die Funktionen von Claude Code erweitern, indem Sie es mit diesem MCP-Server verbinden und so eine semantische Suche in Ihrer bestehenden Codebasis ermöglichen.

mcp-server-qdrant einrichten

  1. 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
    
  2. Überprüfen Sie, ob der Server hinzugefügt wurde:

    claude mcp list
    

Semantische Codesuche in Claude Code verwenden

Die Toolbeschreibungen in TOOL_STORE_DESCRIPTION und TOOL_FIND_DESCRIPTION geben Claude Code vor, wie der MCP-Server zu verwenden ist. Die oben angegebenen Beschreibungen sind Beispiele und müssen möglicherweise an Ihren konkreten Anwendungsfall angepasst werden. Claude Code sollte jedoch bereits Folgendes können:

  1. Mit dem Tool qdrant-store Codeausschnitte samt Beschreibungen speichern.
  2. Mit dem Tool qdrant-find mithilfe natürlichsprachlicher Abfragen nach relevanten Codeausschnitten 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 Inspector 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 folgenden Schaltflächen:

Install with UVX in VS Code Install with UVX in VS Code Insiders

Install with Docker in VS Code Install with Docker in VS Code Insiders

Manuelle Installation

Fügen Sie den folgenden JSON-Block zur Datei „User Settings (JSON)“ in VS Code hinzu. Drücken Sie dazu Ctrl + Shift + P und geben Sie Preferences: Open User Settings (JSON) ein.

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

Wenn Sie stattdessen Docker verwenden möchten, fügen Sie 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 Folgendes 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 zur Verbesserung von mcp-server-qdrant haben oder einen Fehler melden möchten, erstellen 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 startet sowohl eine Client-Benutzeroberfläche (Standardport 5173) als auch einen MCP-Proxyserver (Standardport 3000). Ö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

Rufen Sie nach dem Start in Ihrem Browser http://localhost:5173 auf, um die Inspector-Oberfläche zu öffnen.

Lizenz

Dieser MCP-Server ist unter der Apache License 2.0 lizenziert. Das bedeutet, dass Sie die Software gemäß den Bedingungen der Apache License 2.0 frei verwenden, ändern und verbreiten dürfen. Weitere Informationen finden Sie in der LICENSE-Datei im Projekt-Repository.

Datenschutz und Support