Qdrant MCP Server

How to use

Use an MCP client to interact with the Qdrant MCP Server. You can store text as embeddings, search for similar text using embeddings, and manage vectors in collections. The server also supports batch operations, vector searches within a collection, and filtering by metadata. Typical workflows include converting your text into embeddings, upserting those vectors into a designated collection, and querying for content similar to a given prompt.

How to install

Prerequisites you need on your system before installing are Python and pip. You should also have access to a Qdrant instance to connect to. Follow these steps to install and run the MCP server locally.

pip install -e .
qdrant-mcp-server

Configuration and startup notes

Configure the server using environment variables to tailor the Qdrant connection and default embedding settings. Create a .env file based on the provided template and adjust the values for your environment.

# Qdrant connection settings
QDRANT_HOST=localhost
QDRANT_PORT=6333
QDRANT_API_KEY=
QDRANT_VERIFY_SSL=True  # Set to False if using self-signed certificates

# Default settings
DEFAULT_COLLECTION_NAME=default_collection
EMBEDDING_MODEL=BAAI/bge-small-en-v1.5

Running with Docker

If you prefer containers, you can run the MCP server in Docker. Build the image and start a container, providing the same Qdrant connection settings via environment variables.

docker build -t qdrant-mcp-server .

# Run the container with your Qdrant settings
docker run -p 8000:8000 --env QDRANT_HOST=<your-qdrant-host> --env QDRANT_PORT=<your-qdrant-port> --env QDRANT_VERIFY_SSL=<True|False> qdrant-mcp-server

Testing the server

Test your setup by exercising the available MCP endpoints from your client. You can verify that text can be embedded, stored, and queried for similarity, and that vector operations such as upserts and filtered searches work as expected.

# Example commands executed by your MCP client (pseudo-methods shown for illustration):
await store_text(text="What is the capital of France?", metadata={"category":"geography", "type":"question"})
await search_similar_text(query="What is Paris the capital of?", limit=5)

Security and backups

Ensure SSL verification is enabled when connecting to Qdrant in production. If you are using a self-signed certificate, temporarily disable verification during testing with QDRANT_VERIFY_SSL set to False, but re-enable it in production.

Notes and troubleshooting

If you encounter connection issues, verify that Qdrant is reachable at the host and port you configured, and that the embedding model is available in your environment. Check that your default collection exists or is created by the server when needed.

Examples of common actions

Store a single piece of text as an embedding and then search for similar content using a query.

await store_text(text="Paris is the capital of France", metadata={"category":"geography"})
await search_similar_text(query="Capital of France?", limit=5)

store_text

Convert text to an embedding vector and store it in the database

search_similar_text

Convert a query to an embedding and find similar vectors

store_texts

Convert multiple texts to embeddings and store them in batch

search_vectors

Search for vectors similar to a given embedding in a collection

upsert_vectors

Upload vectors to a collection for storage and retrieval

filter_search

Search a collection with metadata filters

get_points

Retrieve points by their IDs from a collection

delete_points

Delete points by their IDs from a collection

count_points

Count the number of points in a collection