This repository is an example of how to create a MCP server for Qdrant, a vector search engine. 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. 1. qdrant-store - Store some information in the Qdrant database - information (string): Information to store - metadata (JSO
Add this skill
npx mdskills install qdrant/mcp-server-qdrantWell-documented MCP server providing semantic memory storage and retrieval via Qdrant vector database
1# mcp-server-qdrant: A Qdrant MCP server23[](https://smithery.ai/protocol/mcp-server-qdrant)45> The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol that enables6> seamless integration between LLM applications and external data sources and tools. Whether you're building an7> AI-powered IDE, enhancing a chat interface, or creating custom AI workflows, MCP provides a standardized way to8> connect LLMs with the context they need.910This repository is an example of how to create a MCP server for [Qdrant](https://qdrant.tech/), a vector search engine.1112## Overview1314An official Model Context Protocol server for keeping and retrieving memories in the Qdrant vector search engine.15It acts as a semantic memory layer on top of the Qdrant database.1617## Components1819### Tools20211. `qdrant-store`22 - Store some information in the Qdrant database23 - Input:24 - `information` (string): Information to store25 - `metadata` (JSON): Optional metadata to store26 - `collection_name` (string): Name of the collection to store the information in. This field is required if there are no default collection name.27 If there is a default collection name, this field is not enabled.28 - Returns: Confirmation message292. `qdrant-find`30 - Retrieve relevant information from the Qdrant database31 - Input:32 - `query` (string): Query to use for searching33 - `collection_name` (string): Name of the collection to store the information in. This field is required if there are no default collection name.34 If there is a default collection name, this field is not enabled.35 - Returns: Information stored in the Qdrant database as separate messages3637## Environment Variables3839The configuration of the server is done using environment variables:4041| Name | Description | Default Value |42|--------------------------|---------------------------------------------------------------------|-------------------------------------------------------------------|43| `QDRANT_URL` | URL of the Qdrant server | None |44| `QDRANT_API_KEY` | API key for the Qdrant server | None |45| `COLLECTION_NAME` | Name of the default collection to use. | None |46| `QDRANT_LOCAL_PATH` | Path to the local Qdrant database (alternative to `QDRANT_URL`) | None |47| `EMBEDDING_PROVIDER` | Embedding provider to use (currently only "fastembed" is supported) | `fastembed` |48| `EMBEDDING_MODEL` | Name of the embedding model to use | `sentence-transformers/all-MiniLM-L6-v2` |49| `TOOL_STORE_DESCRIPTION` | Custom description for the store tool | See default in [`settings.py`](src/mcp_server_qdrant/settings.py) |50| `TOOL_FIND_DESCRIPTION` | Custom description for the find tool | See default in [`settings.py`](src/mcp_server_qdrant/settings.py) |5152Note: You cannot provide both `QDRANT_URL` and `QDRANT_LOCAL_PATH` at the same time.5354> [!IMPORTANT]55> Command-line arguments are not supported anymore! Please use environment variables for all configuration.5657### FastMCP Environment Variables5859Since `mcp-server-qdrant` is based on FastMCP, it also supports all the FastMCP environment variables. The most60important ones are listed below:6162| Environment Variable | Description | Default Value |63|---------------------------------------|-----------------------------------------------------------|---------------|64| `FASTMCP_DEBUG` | Enable debug mode | `false` |65| `FASTMCP_LOG_LEVEL` | Set logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL) | `INFO` |66| `FASTMCP_HOST` | Host address to bind the server to | `127.0.0.1` |67| `FASTMCP_PORT` | Port to run the server on | `8000` |68| `FASTMCP_WARN_ON_DUPLICATE_RESOURCES` | Show warnings for duplicate resources | `true` |69| `FASTMCP_WARN_ON_DUPLICATE_TOOLS` | Show warnings for duplicate tools | `true` |70| `FASTMCP_WARN_ON_DUPLICATE_PROMPTS` | Show warnings for duplicate prompts | `true` |71| `FASTMCP_DEPENDENCIES` | List of dependencies to install in the server environment | `[]` |7273## Installation7475### Using uvx7677When using [`uvx`](https://docs.astral.sh/uv/guides/tools/#running-tools) no specific installation is needed to directly run *mcp-server-qdrant*.7879```shell80QDRANT_URL="http://localhost:6333" \81COLLECTION_NAME="my-collection" \82EMBEDDING_MODEL="sentence-transformers/all-MiniLM-L6-v2" \83uvx mcp-server-qdrant84```8586#### Transport Protocols8788The server supports different transport protocols that can be specified using the `--transport` flag:8990```shell91QDRANT_URL="http://localhost:6333" \92COLLECTION_NAME="my-collection" \93uvx mcp-server-qdrant --transport sse94```9596Supported transport protocols:9798- `stdio` (default): Standard input/output transport, might only be used by local MCP clients99- `sse`: Server-Sent Events transport, perfect for remote clients100- `streamable-http`: Streamable HTTP transport, perfect for remote clients, more recent than SSE101102The default transport is `stdio` if not specified.103104When SSE transport is used, the server will listen on the specified port and wait for incoming connections. The default105port is 8000, however it can be changed using the `FASTMCP_PORT` environment variable.106107```shell108QDRANT_URL="http://localhost:6333" \109COLLECTION_NAME="my-collection" \110FASTMCP_PORT=1234 \111uvx mcp-server-qdrant --transport sse112```113114### Using Docker115116A Dockerfile is available for building and running the MCP server:117118```bash119# Build the container120docker build -t mcp-server-qdrant .121122# Run the container123docker run -p 8000:8000 \124 -e FASTMCP_HOST="0.0.0.0" \125 -e QDRANT_URL="http://your-qdrant-server:6333" \126 -e QDRANT_API_KEY="your-api-key" \127 -e COLLECTION_NAME="your-collection" \128 mcp-server-qdrant129```130131> [!TIP]132> Please note that we set `FASTMCP_HOST="0.0.0.0"` to make the server listen on all network interfaces. This is133> necessary when running the server in a Docker container.134135### Installing via Smithery136137To install Qdrant MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/protocol/mcp-server-qdrant):138139```bash140npx @smithery/cli install mcp-server-qdrant --client claude141```142143### Manual configuration of Claude Desktop144145To use this server with the Claude Desktop app, add the following configuration to the "mcpServers" section of your146`claude_desktop_config.json`:147148```json149{150 "qdrant": {151 "command": "uvx",152 "args": ["mcp-server-qdrant"],153 "env": {154 "QDRANT_URL": "https://xyz-example.eu-central.aws.cloud.qdrant.io:6333",155 "QDRANT_API_KEY": "your_api_key",156 "COLLECTION_NAME": "your-collection-name",157 "EMBEDDING_MODEL": "sentence-transformers/all-MiniLM-L6-v2"158 }159 }160}161```162163For local Qdrant mode:164165```json166{167 "qdrant": {168 "command": "uvx",169 "args": ["mcp-server-qdrant"],170 "env": {171 "QDRANT_LOCAL_PATH": "/path/to/qdrant/database",172 "COLLECTION_NAME": "your-collection-name",173 "EMBEDDING_MODEL": "sentence-transformers/all-MiniLM-L6-v2"174 }175 }176}177```178179This MCP server will automatically create a collection with the specified name if it doesn't exist.180181By default, the server will use the `sentence-transformers/all-MiniLM-L6-v2` embedding model to encode memories.182For the time being, only [FastEmbed](https://qdrant.github.io/fastembed/) models are supported.183184## Support for other tools185186This MCP server can be used with any MCP-compatible client. For example, you can use it with187[Cursor](https://docs.cursor.com/context/model-context-protocol) and [VS Code](https://code.visualstudio.com/docs), which provide built-in support for the Model Context188Protocol.189190### Using with Cursor/Windsurf191192You can configure this MCP server to work as a code search tool for Cursor or Windsurf by customizing the tool193descriptions:194195```bash196QDRANT_URL="http://localhost:6333" \197COLLECTION_NAME="code-snippets" \198TOOL_STORE_DESCRIPTION="Store reusable code snippets for later retrieval. \199The 'information' parameter should contain a natural language description of what the code does, \200while the actual code should be included in the 'metadata' parameter as a 'code' property. \201The value of 'metadata' is a Python dictionary with strings as keys. \202Use this whenever you generate some code snippet." \203TOOL_FIND_DESCRIPTION="Search for relevant code snippets based on natural language descriptions. \204The 'query' parameter should describe what you're looking for, \205and the tool will return the most relevant code snippets. \206Use this when you need to find existing code snippets for reuse or reference." \207uvx mcp-server-qdrant --transport sse # Enable SSE transport208```209210In Cursor/Windsurf, you can then configure the MCP server in your settings by pointing to this running server using211SSE transport protocol. The description on how to add an MCP server to Cursor can be found in the [Cursor212documentation](https://docs.cursor.com/context/model-context-protocol#adding-an-mcp-server-to-cursor). If you are213running Cursor/Windsurf locally, you can use the following URL:214215```216http://localhost:8000/sse217```218219> [!TIP]220> We suggest SSE transport as a preferred way to connect Cursor/Windsurf to the MCP server, as it can support remote221> connections. That makes it easy to share the server with your team or use it in a cloud environment.222223This configuration transforms the Qdrant MCP server into a specialized code search tool that can:2242251. Store code snippets, documentation, and implementation details2262. Retrieve relevant code examples based on semantic search2273. Help developers find specific implementations or usage patterns228229You can populate the database by storing natural language descriptions of code snippets (in the `information` parameter)230along with the actual code (in the `metadata.code` property), and then search for them using natural language queries231that describe what you're looking for.232233> [!NOTE]234> The tool descriptions provided above are examples and may need to be customized for your specific use case. Consider235> adjusting the descriptions to better match your team's workflow and the specific types of code snippets you want to236> store and retrieve.237238**If you have successfully installed the `mcp-server-qdrant`, but still can't get it to work with Cursor, please239consider creating the [Cursor rules](https://docs.cursor.com/context/rules-for-ai) so the MCP tools are always used when240the agent produces a new code snippet.** You can restrict the rules to only work for certain file types, to avoid using241the MCP server for the documentation or other types of content.242243### Using with Claude Code244245You can enhance Claude Code's capabilities by connecting it to this MCP server, enabling semantic search over your246existing codebase.247248#### Setting up mcp-server-qdrant2492501. Add the MCP server to Claude Code:251252 ```shell253 # Add mcp-server-qdrant configured for code search254 claude mcp add code-search \255 -e QDRANT_URL="http://localhost:6333" \256 -e COLLECTION_NAME="code-repository" \257 -e EMBEDDING_MODEL="sentence-transformers/all-MiniLM-L6-v2" \258 -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." \259 -e TOOL_FIND_DESCRIPTION="Search for relevant code snippets using natural language. The 'query' parameter should describe the functionality you're looking for." \260 -- uvx mcp-server-qdrant261 ```2622632. Verify the server was added:264265 ```shell266 claude mcp list267 ```268269#### Using Semantic Code Search in Claude Code270271Tool descriptions, specified in `TOOL_STORE_DESCRIPTION` and `TOOL_FIND_DESCRIPTION`, guide Claude Code on how to use272the MCP server. The ones provided above are examples and may need to be customized for your specific use case. However,273Claude Code should be already able to:2742751. Use the `qdrant-store` tool to store code snippets with descriptions.2762. Use the `qdrant-find` tool to search for relevant code snippets using natural language.277278### Run MCP server in Development Mode279280The MCP server can be run in development mode using the `mcp dev` command. This will start the server and open the MCP281inspector in your browser.282283```shell284COLLECTION_NAME=mcp-dev fastmcp dev src/mcp_server_qdrant/server.py285```286287### Using with VS Code288289For one-click installation, click one of the install buttons below:290291[](https://insiders.vscode.dev/redirect/mcp/install?name=qdrant&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-server-qdrant%22%5D%2C%22env%22%3A%7B%22QDRANT_URL%22%3A%22%24%7Binput%3AqdrantUrl%7D%22%2C%22QDRANT_API_KEY%22%3A%22%24%7Binput%3AqdrantApiKey%7D%22%2C%22COLLECTION_NAME%22%3A%22%24%7Binput%3AcollectionName%7D%22%7D%7D&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22qdrantUrl%22%2C%22description%22%3A%22Qdrant+URL%22%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22qdrantApiKey%22%2C%22description%22%3A%22Qdrant+API+Key%22%2C%22password%22%3Atrue%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22collectionName%22%2C%22description%22%3A%22Collection+Name%22%7D%5D) [](https://insiders.vscode.dev/redirect/mcp/install?name=qdrant&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-server-qdrant%22%5D%2C%22env%22%3A%7B%22QDRANT_URL%22%3A%22%24%7Binput%3AqdrantUrl%7D%22%2C%22QDRANT_API_KEY%22%3A%22%24%7Binput%3AqdrantApiKey%7D%22%2C%22COLLECTION_NAME%22%3A%22%24%7Binput%3AcollectionName%7D%22%7D%7D&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22qdrantUrl%22%2C%22description%22%3A%22Qdrant+URL%22%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22qdrantApiKey%22%2C%22description%22%3A%22Qdrant+API+Key%22%2C%22password%22%3Atrue%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22collectionName%22%2C%22description%22%3A%22Collection+Name%22%7D%5D&quality=insiders)292293[](https://insiders.vscode.dev/redirect/mcp/install?name=qdrant&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-p%22%2C%228000%3A8000%22%2C%22-i%22%2C%22--rm%22%2C%22-e%22%2C%22QDRANT_URL%22%2C%22-e%22%2C%22QDRANT_API_KEY%22%2C%22-e%22%2C%22COLLECTION_NAME%22%2C%22mcp-server-qdrant%22%5D%2C%22env%22%3A%7B%22QDRANT_URL%22%3A%22%24%7Binput%3AqdrantUrl%7D%22%2C%22QDRANT_API_KEY%22%3A%22%24%7Binput%3AqdrantApiKey%7D%22%2C%22COLLECTION_NAME%22%3A%22%24%7Binput%3AcollectionName%7D%22%7D%7D&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22qdrantUrl%22%2C%22description%22%3A%22Qdrant+URL%22%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22qdrantApiKey%22%2C%22description%22%3A%22Qdrant+API+Key%22%2C%22password%22%3Atrue%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22collectionName%22%2C%22description%22%3A%22Collection+Name%22%7D%5D) [](https://insiders.vscode.dev/redirect/mcp/install?name=qdrant&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-p%22%2C%228000%3A8000%22%2C%22-i%22%2C%22--rm%22%2C%22-e%22%2C%22QDRANT_URL%22%2C%22-e%22%2C%22QDRANT_API_KEY%22%2C%22-e%22%2C%22COLLECTION_NAME%22%2C%22mcp-server-qdrant%22%5D%2C%22env%22%3A%7B%22QDRANT_URL%22%3A%22%24%7Binput%3AqdrantUrl%7D%22%2C%22QDRANT_API_KEY%22%3A%22%24%7Binput%3AqdrantApiKey%7D%22%2C%22COLLECTION_NAME%22%3A%22%24%7Binput%3AcollectionName%7D%22%7D%7D&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22qdrantUrl%22%2C%22description%22%3A%22Qdrant+URL%22%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22qdrantApiKey%22%2C%22description%22%3A%22Qdrant+API+Key%22%2C%22password%22%3Atrue%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22collectionName%22%2C%22description%22%3A%22Collection+Name%22%7D%5D&quality=insiders)294295#### Manual Installation296297Add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing `Ctrl + Shift + P` and typing `Preferences: Open User Settings (JSON)`.298299```json300{301 "mcp": {302 "inputs": [303 {304 "type": "promptString",305 "id": "qdrantUrl",306 "description": "Qdrant URL"307 },308 {309 "type": "promptString",310 "id": "qdrantApiKey",311 "description": "Qdrant API Key",312 "password": true313 },314 {315 "type": "promptString",316 "id": "collectionName",317 "description": "Collection Name"318 }319 ],320 "servers": {321 "qdrant": {322 "command": "uvx",323 "args": ["mcp-server-qdrant"],324 "env": {325 "QDRANT_URL": "${input:qdrantUrl}",326 "QDRANT_API_KEY": "${input:qdrantApiKey}",327 "COLLECTION_NAME": "${input:collectionName}"328 }329 }330 }331 }332}333```334335Or if you prefer using Docker, add this configuration instead:336337```json338{339 "mcp": {340 "inputs": [341 {342 "type": "promptString",343 "id": "qdrantUrl",344 "description": "Qdrant URL"345 },346 {347 "type": "promptString",348 "id": "qdrantApiKey",349 "description": "Qdrant API Key",350 "password": true351 },352 {353 "type": "promptString",354 "id": "collectionName",355 "description": "Collection Name"356 }357 ],358 "servers": {359 "qdrant": {360 "command": "docker",361 "args": [362 "run",363 "-p", "8000:8000",364 "-i",365 "--rm",366 "-e", "QDRANT_URL",367 "-e", "QDRANT_API_KEY",368 "-e", "COLLECTION_NAME",369 "mcp-server-qdrant"370 ],371 "env": {372 "QDRANT_URL": "${input:qdrantUrl}",373 "QDRANT_API_KEY": "${input:qdrantApiKey}",374 "COLLECTION_NAME": "${input:collectionName}"375 }376 }377 }378 }379}380```381382Alternatively, you can create a `.vscode/mcp.json` file in your workspace with the following content:383384```json385{386 "inputs": [387 {388 "type": "promptString",389 "id": "qdrantUrl",390 "description": "Qdrant URL"391 },392 {393 "type": "promptString",394 "id": "qdrantApiKey",395 "description": "Qdrant API Key",396 "password": true397 },398 {399 "type": "promptString",400 "id": "collectionName",401 "description": "Collection Name"402 }403 ],404 "servers": {405 "qdrant": {406 "command": "uvx",407 "args": ["mcp-server-qdrant"],408 "env": {409 "QDRANT_URL": "${input:qdrantUrl}",410 "QDRANT_API_KEY": "${input:qdrantApiKey}",411 "COLLECTION_NAME": "${input:collectionName}"412 }413 }414 }415}416```417418For workspace configuration with Docker, use this in `.vscode/mcp.json`:419420```json421{422 "inputs": [423 {424 "type": "promptString",425 "id": "qdrantUrl",426 "description": "Qdrant URL"427 },428 {429 "type": "promptString",430 "id": "qdrantApiKey",431 "description": "Qdrant API Key",432 "password": true433 },434 {435 "type": "promptString",436 "id": "collectionName",437 "description": "Collection Name"438 }439 ],440 "servers": {441 "qdrant": {442 "command": "docker",443 "args": [444 "run",445 "-p", "8000:8000",446 "-i",447 "--rm",448 "-e", "QDRANT_URL",449 "-e", "QDRANT_API_KEY",450 "-e", "COLLECTION_NAME",451 "mcp-server-qdrant"452 ],453 "env": {454 "QDRANT_URL": "${input:qdrantUrl}",455 "QDRANT_API_KEY": "${input:qdrantApiKey}",456 "COLLECTION_NAME": "${input:collectionName}"457 }458 }459 }460}461```462463## Contributing464465If you have suggestions for how mcp-server-qdrant could be improved, or want to report a bug, open an issue!466We'd love all and any contributions.467468### Testing `mcp-server-qdrant` locally469470The [MCP inspector](https://github.com/modelcontextprotocol/inspector) is a developer tool for testing and debugging MCP471servers. It runs both a client UI (default port 5173) and an MCP proxy server (default port 3000). Open the client UI in472your browser to use the inspector.473474```shell475QDRANT_URL=":memory:" COLLECTION_NAME="test" \476fastmcp dev src/mcp_server_qdrant/server.py477```478479Once started, open your browser to http://localhost:5173 to access the inspector interface.480481## License482483This MCP server is licensed under the Apache License 2.0. This means you are free to use, modify, and distribute the484software, subject to the terms and conditions of the Apache License 2.0. For more details, please see the LICENSE file485in the project repository.486
Full transparency — inspect the skill content before installing.