📌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

1. qdrant-store

   • Store information in the Qdrant database
   • Input:
     • information (string): Information to store
     • metadata (JSON): Optional metadata to store
     • collection_name (string): Name of the collection to store the information in. Required if there is no default collection name.
   • Returns: Confirmation message

2. qdrant-find

   • Retrieve relevant information from the Qdrant database
   • Input:
     • query (string): Query to use for searching
     • collection_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

1. 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

2. 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.