home / mcp / qdrant mcp server

Qdrant MCP Server

Qdrant MCP server compatible with multiple embedding models for efficient vector search and retrieval

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "andrewlwn77-qdrant-mcp": {
      "command": "python",
      "args": [
        "-m",
        "qdrant_mcp.server"
      ],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "OPENAI_API_KEY": "your-api-key",
        "QDRANT_API_KEY": "your-qdrant-api-key",
        "EMBEDDING_MODEL": "text-embedding-3-small",
        "EMBEDDING_PROVIDER": "openai"
      }
    }
  }
}

You run a memory-enabled MCP server that uses Qdrant as a vector store to store, search, and retrieve information by semantic similarity. You can choose lightweight cloud-free OpenAI embeddings or local Sentence Transformers, attach custom metadata to items, and perform store, find, delete, and list operations through simple MCP tooling.

How to use

Store content with optional metadata and then search it using vector similarity. You can find relevant results by querying with natural language, filter on metadata, and adjust how many results you want. You also have tools to inspect your memory store, remove items by id, and list available collections within the Qdrant backend.

How to install

Prerequisites you need on your system: Python 3.8+ and a working network connection. If you plan to use the lightweight OpenAI embedding path, you will also need an OpenAI API key.

# Quick start with OpenAI embeddings (lightweight, no ML deps)
uvx qdrant-mcp

If you want local embeddings with Sentence Transformers (includes PyTorch and ML libraries), install with local support.

# Start with local embeddings (includes Torch and related dependencies)
uvx --with sentence-transformers qdrant-mcp

For development or contributing, you can install from source. Use the basic OpenAI path first, then add local embeddings as needed.

# Clone the project and install
git clone https://github.com/andrewlwn77/qdrant-mcp.git
cd qdrant-mcp

# Basic install (OpenAI embeddings only)
pip install -e .

# With local embeddings support
pip install -e . sentence-transformers

Configuration and running tips

Configure which embedding provider you want and point to your Qdrant instance. You can use environment variables to switch between OpenAI and Sentence Transformers and to set the Qdrant endpoint.

# OpenAI embeddings
export EMBEDDING_PROVIDER=openai
export EMBEDDING_MODEL=text-embedding-3-small
export OPENAI_API_KEY=your-api-key

# Sentence Transformers (local embeddings)
export EMBEDDING_PROVIDER=sentence-transformers
export EMBEDDING_MODEL=all-MiniLM-L6-v2
export QDRANT_URL=http://localhost:6333
export QDRANT_API_KEY=your-qdrant-api-key

Using MCP tools

You work with a set of MCP tools to store, find, delete, and list items, plus inspect collections.

# Store content with embeddings
{
  "content": "The capital of France is Paris",
  "metadata": "{\"category\": \"geography\", \"type\": \"fact\"}",
  "id": "optional-custom-id"
}

Search for relevant information with a query and optional filters.

{
  "query": "What is the capital of France?",
  "limit": 5,
  "filter": "{\"category\": \"geography\"}",
  "score_threshold": 0.7
}

Remove stored items by ids or list items within your collection.

{
  "ids": "id1,id2,id3"
}

Inspect available collections or get info about the current collection.

{}

Integration and examples

OpenAI embeddings path is lightweight and avoids ML dependencies, suitable for quick setups. Local embeddings path uses Sentence Transformers and runs on your machine.

You can run the MCP server in development mode directly or via the MCP CLI for a streamlined workflow.

# Development mode
python -m qdrant_mcp.server

# With MCP CLI
mcp dev src/qdrant_mcp/server.py

Available tools

qdrant-store

Store content with semantic embeddings and optional metadata, ready for semantic search.

qdrant-find

Search stored content by a natural language query, with optional filters and score thresholds.

qdrant-delete

Delete stored items by their IDs to remove them from memory.

qdrant-list-collections

List all collections present in the Qdrant backend.

qdrant-collection-info

Get information about the current collection and its settings.