mcp-server-qdrant

Retrieves relevant information from Qdrant collections using semantic similarity matching rather than keyword search. The server converts user queries into embeddings using configurable embedding providers (OpenAI, Ollama, or local models), then performs vector similarity search against stored embeddings to find contextually relevant results. This enables natural language queries to match conceptually similar content even without exact keyword overlap.

Stores text content as semantic embeddings in Qdrant collections with associated structured metadata for filtering and organization. The server converts input text to embeddings via configured embedding providers, then persists both the embedding vector and metadata (custom key-value pairs) to Qdrant. This enables later retrieval with optional metadata-based filtering (e.g., retrieve only embeddings where source='documentation' AND date>'2024-01-01').

Supports filtering search results by metadata attributes (e.g., source='documentation', date>'2024-01-01') applied after vector similarity search completes. The server accepts metadata filter expressions in search requests, performs the vector similarity search first, then filters results by metadata criteria. This enables combining semantic relevance with structured filtering, though with the caveat that filtering happens post-search rather than during the vector search phase.

Centralizes all server configuration (Qdrant connection, embedding provider, collections, transport protocol) in environment variables, enabling deployment without code changes or config files. The server reads environment variables at startup and applies them to initialize connections, register tools, and configure behavior. This pattern enables containerized deployments, CI/CD pipelines, and multi-environment setups where configuration varies but code is identical.

Manages multiple Qdrant collections within a single MCP server instance, with per-collection tool registration and optional filtering to expose only specific collections to clients. The server loads collection configurations from environment variables or config files, dynamically registers qdrant-store and qdrant-find tools for each collection, and can selectively hide collections based on client permissions or deployment context. This enables a single server to serve multiple use cases (e.g., code search, documentation search, conversation memory) with isolated data and independent embedding strategies.

Abstracts embedding generation behind a provider interface supporting OpenAI, Ollama, and local Hugging Face models. The server loads the configured embedding provider at startup (via environment variables), then transparently generates embeddings for all store and search operations without exposing provider details to clients. This enables switching embedding models (e.g., from OpenAI to local Ollama) by changing configuration, not code, and allows different collections to use different embedding models simultaneously.

Implements the Model Context Protocol (MCP) specification to expose vector storage and search operations as standardized tools callable by MCP-compatible clients (Claude, Cursor, Windsurf, VS Code). The server registers tools with MCP-compliant schemas (input/output types, descriptions), handles MCP protocol messages (tool calls, responses), and manages the stdio/SSE/HTTP transport layer. This enables LLM clients to invoke semantic search and storage operations as native tools without custom integrations.

Provides an optional read-only mode that disables write operations (qdrant-store tool) while preserving search functionality (qdrant-find tool). This is configured via environment variable at server startup and prevents accidental or malicious data modification in production environments. The server registers only the qdrant-find tool when read-only mode is enabled, effectively removing the ability to store new data while maintaining full search capabilities.

Supports connections to both local file-based Qdrant instances (for development/testing) and remote Qdrant Cloud or self-hosted servers (for production). The server accepts Qdrant connection parameters (URL, API key) via environment variables and abstracts the connection details behind a QdrantConnector interface. This enables the same server code to work across development (local SQLite-backed Qdrant) and production (cloud-hosted Qdrant) without code changes.

Provides a Dockerfile and Docker Compose configuration for containerized deployment of the MCP server, with all settings (Qdrant connection, embedding provider, collections) configurable via environment variables. The container image includes Python 3.10+, dependencies, and the server code, enabling deployment to Kubernetes, Docker Swarm, or other container orchestration platforms. Environment variables passed at container runtime configure the server without rebuilding images.

Abstracts MCP communication over multiple transport protocols (stdio, SSE, HTTP) via a pluggable transport layer. The server can operate in stdio mode (for direct process communication), SSE mode (for server-sent events over HTTP), or streamable HTTP mode (for request/response over HTTP), selected via configuration. This enables the same server code to work with different client integration patterns without code changes.

Generates human-readable tool descriptions for qdrant-store and qdrant-find tools based on collection metadata and configuration. The server creates descriptive text explaining what each tool does, what parameters it accepts, and what results it returns, enabling LLM clients to understand tool purpose without documentation. Descriptions can be customized via configuration to reflect domain-specific language (e.g., 'Search our code repository' vs 'Perform semantic search').