Qdrant MCP
официальныйСемантический поиск с использованием векторной базы данных Qdrant.
Что можно делать с Qdrant MCP?
- Сохранение воспоминаний — Попросите ассистента сохранить информацию с необязательными метаданными в коллекцию Qdrant с помощью
qdrant-store. - Семантический поиск — Находите релевантную сохранённую информацию с помощью запроса на естественном языке
queryиqdrant-find. - Выбор коллекции — Указывайте конкретную
collection_nameдля каждого вызова или задайте коллекцию по умолчанию черезCOLLECTION_NAME. - Настройка описаний инструментов — Измените
TOOL_STORE_DESCRIPTIONиTOOL_FIND_DESCRIPTION, чтобы превратить сервер в инструмент поиска фрагментов кода. - Режим только для чтения — Включите
QDRANT_READ_ONLY, чтобы отключить сохранение и разрешить только поиск. - Настройка результатов — Ограничьте количество результатов поиска с помощью
QDRANT_SEARCH_LIMITи выберите модель эмбеддингов черезEMBEDDING_MODEL.
Документация
mcp-server-qdrant: MCP-сервер Qdrant
Model Context Protocol (MCP) — это открытый протокол, обеспечивающий бесшовную интеграцию приложений на основе LLM с внешними источниками данных и инструментами. Создаёте ли вы IDE с поддержкой ИИ, расширяете интерфейс чата или разрабатываете собственные рабочие процессы с ИИ, MCP предоставляет стандартизированный способ подключить LLM к необходимому контексту.
Этот репозиторий — пример создания MCP-сервера для Qdrant, векторной поисковой системы.
Обзор
Официальный сервер Model Context Protocol для хранения и извлечения воспоминаний в векторной поисковой системе Qdrant. Он служит слоем семантической памяти поверх базы данных Qdrant.
Компоненты
Инструменты
qdrant-store- Сохранить информацию в базе данных Qdrant
- Входные данные:
information(string): информация для сохраненияmetadata(JSON): необязательные метаданные для сохраненияcollection_name(string): имя коллекции, в которой нужно сохранить информацию. Это поле обязательно, если имя коллекции по умолчанию не задано. Если имя коллекции по умолчанию задано, это поле недоступно.
- Возвращает: сообщение с подтверждением
qdrant-find- Извлечь релевантную информацию из базы данных Qdrant
- Входные данные:
query(string): запрос для поискаcollection_name(string): имя коллекции, в которой нужно сохранить информацию. Это поле обязательно, если имя коллекции по умолчанию не задано. Если имя коллекции по умолчанию задано, это поле недоступно.
- Возвращает: информацию, сохранённую в базе данных Qdrant, в виде отдельных сообщений
Переменные окружения
Настройка выполняется с помощью переменных окружения. Единственный аргумент командной строки — --transport, который используется для выбора транспортного протокола.
[!NOTE] Нельзя одновременно указывать
QDRANT_URLиQDRANT_LOCAL_PATH.
| Имя | Описание | Значение по умолчанию |
|---|---|---|
QDRANT_URL | URL-адрес сервера Qdrant | None |
QDRANT_API_KEY | Ключ API сервера Qdrant | None |
COLLECTION_NAME | Имя используемой коллекции по умолчанию | None |
QDRANT_LOCAL_PATH | Путь к локальной базе данных Qdrant (альтернатива QDRANT_URL) | None |
EMBEDDING_PROVIDER | Используемый поставщик эмбеддингов (сейчас поддерживается только "fastembed") | fastembed |
EMBEDDING_MODEL | Имя используемой модели эмбеддингов | sentence-transformers/all-MiniLM-L6-v2 |
TOOL_STORE_DESCRIPTION | Пользовательское описание инструмента store | См. значение по умолчанию в settings.py |
TOOL_FIND_DESCRIPTION | Пользовательское описание инструмента find | См. значение по умолчанию в settings.py |
QDRANT_SEARCH_LIMIT | Максимальное количество результатов поиска | 10 |
QDRANT_READ_ONLY | Включить режим только для чтения (отключает инструмент qdrant-store) | false |
Переменные окружения FastMCP
Поскольку mcp-server-qdrant основан на FastMCP, он также поддерживает все переменные окружения FastMCP. Ниже перечислены наиболее
важные из них:
| Переменная окружения | Описание | Значение по умолчанию |
|---|---|---|
FASTMCP_LOG_LEVEL | Задать уровень ведения журнала (DEBUG, INFO, WARNING, ERROR, CRITICAL) | INFO |
FASTMCP_DEBUG | Включить режим отладки | false |
FASTMCP_HOST | Адрес хоста, на котором будет работать сервер (транспорты SSE и HTTP) | 127.0.0.1 |
FASTMCP_PORT | Порт сервера (транспорты SSE и HTTP) | 8000 |
FASTMCP_MASK_ERROR_DETAILS | Скрывать подробности исключений в сообщениях об ошибках инструментов, отправляемых клиентам | false |
[!NOTE] До версии 0.9.0 для этих настроек использовался префикс
FASTMCP_SERVER_, напримерFASTMCP_SERVER_HOST. Старые именаFASTMCP_SERVER_HOST,FASTMCP_SERVER_PORTиFASTMCP_SERVER_DEBUGпо-прежнему работают, но считаются устаревшими и будут удалены в одном из будущих выпусков. Если заданы оба имени, приоритет имеет новое.
Установка
Использование uvx
При использовании uvx специальная установка для непосредственного запуска mcp-server-qdrant не требуется.
QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
EMBEDDING_MODEL="sentence-transformers/all-MiniLM-L6-v2" \
uvx mcp-server-qdrant
Транспортные протоколы
Сервер поддерживает различные транспортные протоколы, которые можно указать с помощью флага --transport:
QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
uvx mcp-server-qdrant --transport sse
Поддерживаемые транспортные протоколы:
stdio(по умолчанию): транспорт стандартного ввода-вывода, может использоваться только локальными MCP-клиентамиsse: транспорт Server-Sent Events, подходит для удалённых клиентовstreamable-http: транспорт Streamable HTTP, подходит для удалённых клиентов и является более новым, чем SSE
Если транспорт не указан, по умолчанию используется stdio.
При использовании транспорта SSE сервер будет прослушивать указанный порт и ожидать входящих подключений. Порт по умолчанию —
8000, но его можно изменить с помощью переменной окружения FASTMCP_PORT.
QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
FASTMCP_PORT=1234 \
uvx mcp-server-qdrant --transport sse
Использование Docker
Для сборки и запуска MCP-сервера доступен Dockerfile:
# Build the container
docker build -t mcp-server-qdrant .
# Run the container
docker run -p 8000:8000 \
-e FASTMCP_HOST="0.0.0.0" \
-e QDRANT_URL="http://your-qdrant-server:6333" \
-e QDRANT_API_KEY="your-api-key" \
-e COLLECTION_NAME="your-collection" \
mcp-server-qdrant
[!TIP] Обратите внимание: мы задаём
FASTMCP_HOST="0.0.0.0", чтобы сервер прослушивал все сетевые интерфейсы. Это необходимо при запуске сервера в контейнере Docker.
Установка через Smithery
Чтобы автоматически установить Qdrant MCP Server для Claude Desktop с помощью Smithery:
npx @smithery/cli install mcp-server-qdrant --client claude
Ручная настройка Claude Desktop
Чтобы использовать этот сервер с приложением Claude Desktop, добавьте следующую конфигурацию в раздел "mcpServers" файла
claude_desktop_config.json:
{
"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"
}
}
}
Для локального режима Qdrant:
{
"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"
}
}
}
Этот MCP-сервер автоматически создаст коллекцию с указанным именем, если она ещё не существует.
По умолчанию сервер использует модель эмбеддингов sentence-transformers/all-MiniLM-L6-v2 для кодирования воспоминаний.
На данный момент поддерживаются только модели FastEmbed.
Поддержка других инструментов
Этот MCP-сервер можно использовать с любым MCP-совместимым клиентом. Например, его можно использовать с Cursor и VS Code, которые имеют встроенную поддержку Model Context Protocol.
Использование с Cursor/Windsurf
Чтобы использовать этот MCP-сервер как инструмент поиска по коду в Cursor или Windsurf, настройте описания инструментов:
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 strings as keys. \
Use this whenever you generate some code snippet." \
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 when you need to find existing code snippets for reuse or reference." \
uvx mcp-server-qdrant --transport sse # Enable SSE transport
Затем в Cursor/Windsurf можно настроить MCP-сервер в параметрах, указав адрес работающего сервера и используя транспортный протокол SSE. Описание добавления MCP-сервера в Cursor можно найти в документации Cursor. Если вы используете Cursor/Windsurf локально, можно указать следующий URL-адрес:
http://localhost:8000/sse
[!TIP] Мы рекомендуем использовать транспорт SSE для подключения Cursor/Windsurf к MCP-серверу, поскольку он поддерживает удалённые подключения. Это позволяет легко делиться сервером с командой или использовать его в облачной среде.
Эта конфигурация превращает MCP-сервер Qdrant в специализированный инструмент поиска по коду, который может:
- Сохранять фрагменты кода, документацию и сведения о реализации
- Находить релевантные примеры кода с помощью семантического поиска
- Помогать разработчикам находить конкретные реализации или шаблоны использования
Можно заполнить базу данных, сохраняя описания фрагментов кода на естественном языке (в параметре information)
вместе с самим кодом (в свойстве metadata.code), а затем искать их с помощью запросов на естественном языке,
описывающих нужные результаты.
[!NOTE] Приведённые выше описания инструментов — это примеры, которые может потребоваться адаптировать под конкретный сценарий использования. Подумайте о том, чтобы изменить описания в соответствии с рабочими процессами вашей команды и типами фрагментов кода, которые вы хотите сохранять и находить.
Если вы успешно установили mcp-server-qdrant, но он по-прежнему не работает с Cursor, попробуйте
создать правила Cursor, чтобы MCP-инструменты всегда использовались, когда
агент создаёт новый фрагмент кода. Можно ограничить правила определёнными типами файлов, чтобы MCP-сервер не использовался
для документации и других типов содержимого.
Использование с Claude Code
Расширьте возможности Claude Code, подключив его к этому MCP-серверу и включив семантический поиск по существующей кодовой базе.
Настройка mcp-server-qdrant
-
Добавьте MCP-сервер в Claude Code:
# Add mcp-server-qdrant configured for code search 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 -
Убедитесь, что сервер добавлен:
claude mcp list
Семантический поиск по коду в Claude Code
Описания инструментов, заданные в TOOL_STORE_DESCRIPTION и TOOL_FIND_DESCRIPTION, указывают Claude Code, как использовать
MCP-сервер. Приведённые выше описания — это примеры, которые может потребоваться адаптировать под конкретный сценарий использования. Однако
Claude Code уже должен уметь:
- Использовать инструмент
qdrant-storeдля сохранения фрагментов кода с описаниями. - Использовать инструмент
qdrant-findдля поиска релевантных фрагментов кода с помощью запросов на естественном языке.
Запуск MCP-сервера в режиме разработки
MCP-сервер можно запустить в режиме разработки с помощью команды mcp dev. Она запустит сервер и откроет MCP
Inspector в браузере.
COLLECTION_NAME=mcp-dev fastmcp dev src/mcp_server_qdrant/server.py
Использование с VS Code
Чтобы установить сервер одним нажатием, нажмите одну из кнопок установки ниже:
Ручная установка
Добавьте следующий блок JSON в файл пользовательских настроек (JSON) в VS Code. Для этого нажмите Ctrl + Shift + P и введите Preferences: Open User Settings (JSON).
{
"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}"
}
}
}
}
}
Если вы предпочитаете использовать 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}"
}
}
}
}
}
Также можно создать файл .vscode/mcp.json в рабочей области со следующим содержимым:
{
"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}"
}
}
}
}
Для настройки рабочей области с Docker используйте это в .vscode/mcp.json:
{
"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}"
}
}
}
}
Участие в разработке
Если у вас есть предложения по улучшению mcp-server-qdrant или вы хотите сообщить об ошибке, создайте issue! Мы будем рады любому вкладу.
Локальное тестирование mcp-server-qdrant
MCP Inspector — это инструмент разработчика для тестирования и отладки MCP- серверов. Он запускает интерфейс клиента (порт по умолчанию — 5173) и прокси-сервер MCP (порт по умолчанию — 3000). Откройте интерфейс клиента в браузере, чтобы воспользоваться Inspector.
QDRANT_URL=":memory:" COLLECTION_NAME="test" \
fastmcp dev src/mcp_server_qdrant/server.py
После запуска откройте в браузере http://localhost:5173, чтобы перейти к интерфейсу Inspector.
Лицензия
Этот MCP-сервер распространяется по лицензии Apache License 2.0. Это означает, что вы можете использовать, изменять и распространять программное обеспечение при соблюдении условий лицензии Apache License 2.0. Подробнее см. в файле LICENSE в репозитории проекта.