mcp-server-qdrant
by: qdrant
Qdrant Model Context Protocol (MCP) server
📌Overview
Purpose: The primary goal of the mcp-server-qdrant is to serve as a Model Context Protocol server that manages and retrieves memories using the Qdrant vector search engine.
Overview: This server functions as a semantic memory layer, facilitating the storage and retrieval of information in the Qdrant database. It is designed to bridge the gap between large language models (LLMs) and external data sources, enhancing AI applications by providing contextual understanding.
Key Features:
-
Memory Storage (qdrant-store): This feature allows users to store information and optional metadata in the Qdrant database, enabling the system to retain relevant data for future reference.
-
Information Retrieval (qdrant-find): Users can query the database to retrieve stored information, which is returned as a series of relevant messages, thus ensuring efficient access to necessary context for LLMs.
mcp-server-qdrant: A Qdrant MCP server
The Model Context Protocol (MCP) is an open protocol that enables seamless integration between LLM applications and external data sources and tools. Whether you're building an AI-powered IDE, enhancing a chat interface, or creating custom AI workflows, MCP provides a standardized way to connect LLMs with the context they need.
This repository is an example of how to create an MCP server for Qdrant, a vector search engine.
Overview
An official Model Context Protocol server for keeping and retrieving memories in the Qdrant vector search engine.
It acts as a semantic memory layer on top of the Qdrant database.
Components
Tools
-
qdrant-store
- Store information in the Qdrant database
- Input:
information
(string): Information to storemetadata
(JSON): Optional metadata to storecollection_name
(string): Name of the collection to store the information in. Required if there is no default collection name.
- Returns: Confirmation message
-
qdrant-find
- Retrieve relevant information from the Qdrant database
- Input:
query
(string): Query to use for searchingcollection_name
(string): Name of the collection to search in. Required if there is no default collection name.
- Returns: Information stored in the Qdrant database as separate messages
Environment Variables
Configuration is done using environment variables:
Name | Description | Default Value |
---|---|---|
QDRANT_URL | URL of the Qdrant server | None |
QDRANT_API_KEY | API key for the Qdrant server | None |
COLLECTION_NAME | Name of the default collection to use | None |
QDRANT_LOCAL_PATH | Path to the local Qdrant database (alternative to QDRANT_URL ) | None |
EMBEDDING_PROVIDER | Embedding provider to use (currently only "fastembed" supported) | fastembed |
EMBEDDING_MODEL | Name of the embedding model to use | sentence-transformers/all-MiniLM-L6-v2 |
TOOL_STORE_DESCRIPTION | Custom description for the store tool | See default in settings.py |
TOOL_FIND_DESCRIPTION | Custom description for the find tool | See default in settings.py |
Note: You cannot provide both QDRANT_URL
and QDRANT_LOCAL_PATH
at the same time.
Command-line arguments are not supported anymore! Please use environment variables for all configuration.
Installation
Using uvx
No specific installation needed to directly run mcp-server-qdrant with uvx:
QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
EMBEDDING_MODEL="sentence-transformers/all-MiniLM-L6-v2" \
uvx mcp-server-qdrant
Transport Protocols
Specify transport protocols with the --transport
flag:
QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
uvx mcp-server-qdrant --transport sse
Supported protocols:
stdio
(default): Local use with standard input/output.sse
: Server-Sent Events transport for remote clients.
Using Docker
Build and run the MCP server in Docker:
# Build the container
docker build -t mcp-server-qdrant .
# Run the container
docker run -p 8000:8000 \
-e QDRANT_URL="http://your-qdrant-server:6333" \
-e QDRANT_API_KEY="your-api-key" \
-e COLLECTION_NAME="your-collection" \
mcp-server-qdrant
Installing via Smithery
Install Qdrant MCP Server for Claude Desktop automatically via Smithery:
npx @smithery/cli install mcp-server-qdrant --client claude
Manual configuration of Claude Desktop
Add the following to the "mcpServers"
section in your claude_desktop_config.json
for remote Qdrant:
{
"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"
}
}
}
For local Qdrant mode:
{
"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"
}
}
}
This MCP server will create the collection automatically if it does not exist. Currently, only FastEmbed models are supported for embeddings.
Support for Other Tools
This MCP server works with any MCP-compatible client, such as Cursor and VS Code, which have built-in support for MCP.
Using with Cursor/Windsurf
Configure the MCP server as a code search tool by customizing tool descriptions:
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 string keys. Use this whenever you generate code snippets." \
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 to find existing code snippets for reuse or reference." \
uvx mcp-server-qdrant --transport sse
In Cursor/Windsurf, configure the MCP server to use SSE transport by connecting to:
http://localhost:8000/sse
SSE transport is preferred for remote connections and easier team or cloud use.
This setup allows:
- Storing code snippets, documentation, and implementation details
- Retrieving relevant code examples via semantic search
- Helping developers find specific implementations or usage patterns
Populate the database by storing natural language descriptions (information
) along with code (metadata.code
), then search via natural language queries.
The tool descriptions above are examples and may need customization for your use case.
If installed but not working with Cursor, consider creating Cursor rules so MCP tools are used when new code snippets are produced, restricting rules by file types if needed.
Using with Claude Code
Enhance Claude Code by connecting it to this MCP server for semantic code search.
Setup
- Add MCP server to Claude Code:
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
- Verify the server was added:
claude mcp list
Usage
Using the tool descriptions guides Claude Code to:
- Store code snippets with descriptions using
qdrant-store
- Search relevant code snippets with
qdrant-find
Run MCP server in Development Mode
Run the MCP server in development mode to start the server and open the MCP inspector:
COLLECTION_NAME=mcp-dev mcp dev src/mcp_server_qdrant/server.py
Open the inspector at http://localhost:5173 to debug and test.
Using with VS Code
For one-click installation, use the UVX or Docker commands integrated with VS Code MCP extension (details omitted for brevity).
Manual Installation
Add one of the following JSON blocks to your User Settings (JSON) in VS Code for UVX:
{
"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}"
}
}
}
}
}
Or, for Docker:
{
"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}"
}
}
}
}
}
You can also create a .vscode/mcp.json
file in your workspace with similar content for workspace-level configuration.
Contributing
Suggestions and bug reports are welcome. Please open an issue to contribute.
Testing Locally
Use the MCP inspector tool for testing and debugging:
QDRANT_URL=":memory:" COLLECTION_NAME="test" \
mcp dev src/mcp_server_qdrant/server.py
Then open http://localhost:5173 in your browser.
License
Licensed under the Apache License 2.0. You are free to use, modify, and distribute the software under the terms of this license. See the LICENSE file in the project repository for details.