Содержание
Как настроить MCP-сервер Qdrant
Черновик готовит редакция с помощью ИИ. За стандарт издания отвечает главный редактор — Валерий Курземнек.
Материал редакции Зерокодера. Счёт по выдаче снят собственным прогоном 22 октября 2026 года; цитаты источников приведены дословно. Обновлено: октябрь 2026.
Как настроить MCP-сервер Qdrant: развернуть Qdrant, задать переменные окружения QDRANT_URL, COLLECTION_NAME и EMBEDDING_MODEL, запустить mcp-server-qdrant через uvx или Docker и подключить его к своему AI-клиенту. Всё поведение сервера определяется переменными окружения, а единственный аргумент командной строки — выбор транспорта. Ниже — рабочий порядок действий, примеры конфигураций и способы проверить, что подключение живо. Мы скачали подборку результатов веб-поиска по запросу «Как настроить MCP-сервер Qdrant»: текст отдали 9 из 10.
Что такое MCP-сервер Qdrant и что он умеет
MCP-сервер Qdrant — это прослойка между AI-клиентом и векторной базой Qdrant. В репозитории проекта на GitHub он описан как пример создания MCP-сервера для Qdrant, векторного поискового движка. В блоге Qdrant ту же конструкцию называют семантическим слоем памяти поверх Qdrant: агент складывает туда фрагменты кода, документацию и рабочие заметки, а потом достаёт нужное по смыслу запроса.
Работает это через Model Context Protocol — открытый протокол, который связывает LLM-приложения с внешними источниками данных и инструментами. В блоге Qdrant его описывают как стандартный способ дать модели контекст, который ей нужен.
Инструментов у сервера два. qdrant-store сохраняет информацию вместе с необязательными метаданными в базе Qdrant. qdrant-find достаёт релевантные записи через семантический поиск. Этого набора хватает, чтобы агент помнил факты о пользователе, искал по кодовой базе и подтягивал примеры перед генерацией нового кода.
Границы продукта стоит держать в голове сразу. В описанном сетевом сценарии сервер обращается к Qdrant по QDRANT_URL. README также поддерживает локальное хранилище через QDRANT_LOCAL_PATH; эти две переменные одновременно задавать нельзя. Он не обучает модель и не заменяет поисковый движок: он отдаёт клиенту инструменты и описания к ним. И он не привязан к одному редактору — в репозитории есть разделы про Claude Desktop, Cursor, Windsurf, Claude Code и VS Code.
Если вы ещё не поднимали саму базу, начните с материала Qdrant: что это, как поднять и сколько займёт на диске. Для сетевого сценария нужен работающий Qdrant; альтернативный локальный режим задаётся через QDRANT_LOCAL_PATH.
Условия доступа и откуда брать актуальные требования
Источник актуальных требований один — репозиторий qdrant/mcp-server-qdrant на GitHub и его страница релизов. Там же лежит README с разделами про установку, переменные окружения, транспорты и подключение к конкретным клиентам. Сверяться нужно именно с ним: проект развивается, и старые инструкции из сторонних обзоров расходятся с текущим состоянием.
Что нужно на входе. Работающий экземпляр Qdrant с адресом вида http://localhost:6333. Имя коллекции, в которой сервер будет хранить записи. Клиент, поддерживающий MCP: Claude Desktop, Cursor, Windsurf, Claude Code, VS Code. Если Qdrant закрыт авторизацией, понадобится API-ключ — переменная QDRANT_API_KEY.
Про зависимости. Сервер построен на FastMCP, поэтому поддерживает все переменные окружения FastMCP. В README отдельно предупреждают, что настройки самого сервера используют префикс FASTMCP_SERVER_ и это может измениться в будущих версиях. Практический вывод: перед обновлением читайте changelog.
Про историю изменений. В одном из релизов авторы прямо пишут, что параметры командной строки больше не поддерживаются и вся конфигурация выполняется переменными окружения. Если вы нашли в интернете пример со старыми флагами, он устарел. Ещё один релиз менял архитектуру: сервер стал классом QdrantMCPServer, от которого можно наследоваться для собственных проектных серверов.
Доступность сервиса из России в прочитанных источниках не описана. Это локальный процесс на вашей машине, который общается с вашим Qdrant, — но какие сетевые ограничения действуют в вашей инфраструктуре, знаете только вы.
Порядок действий: установка и запуск
Порядок из README проекта. Сначала убедитесь, что Qdrant отвечает по своему адресу. Затем задайте переменные окружения и запустите сервер. Ниже — минимальный набор.
Установка через uvx не требует отдельной установки пакета: команда запускает сервер напрямую. В README приведён такой пример:
QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
EMBEDDING_MODEL="sentence-transformers/all-MiniLM-L6-v2" \
uvx mcp-server-qdrant
Транспорт по умолчанию — stdio, и он подходит локальным MCP-клиентам. Для удалённых клиентов переключайтесь на SSE флагом --transport sse. Тогда сервер слушает указанный порт и ждёт входящих подключений; порт по умолчанию — 8000, меняется переменной FASTMCP_SERVER_PORT.
QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
FASTMCP_SERVER_PORT=1234 \
uvx mcp-server-qdrant --transport sse
Запуск в Docker. В репозитории есть Dockerfile. Сборка — docker build -t mcp-server-qdrant ., запуск — с пробросом порта и переменными окружения. Важная деталь из README: внутри контейнера нужно выставить FASTMCP_SERVER_HOST="0.0.0.0", чтобы сервер слушал все сетевые интерфейсы. Без этого он останется на localhost внутри контейнера и снаружи будет недоступен.
Автоматическая установка для Claude Desktop идёт через Smithery: команда npx @smithery/cli install mcp-server-qdrant --client claude прописывает конфигурацию сама. Ручной путь — добавить блок в секцию mcpServers файла claude_desktop_config.json.
Таблица ниже сводит ключевые переменные и их значения по умолчанию из README проекта.
| Переменная | Назначение | Значение по умолчанию |
|---|---|---|
QDRANT_URL |
Адрес сервера Qdrant | не задано |
QDRANT_API_KEY |
Ключ доступа к Qdrant | не задано |
COLLECTION_NAME |
Коллекция для записей | не задано |
FASTMCP_SERVER_HOST |
Адрес привязки сервера | 127.0.0.1 |
FASTMCP_SERVER_PORT |
Порт сервера | 8000 |
FASTMCP_SERVER_DEBUG |
Режим отладки | false |
Учебный пример: поиск по коду и критерии проверки
Сценарий, который разбирают в блоге Qdrant: агент генерирует фронтенд-код, а перед этим ищет похожие примеры в базе. Проблема, которую они описывают, знакома многим — модель тянет устаревший синтаксис библиотеки, на которой обучалась. Решение: дать ей доступ к актуальным примерам через MCP-сервер.
Настройка сводится к переопределению описаний инструментов. Переменные TOOL_STORE_DESCRIPTION и TOOL_FIND_DESCRIPTION объясняют агенту, когда какой инструмент вызывать. В блоге Qdrant приводят пример, где в описании поиска стоит указание всегда искать перед генерацией кода и переиспользовать найденные фрагменты.
Для 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." \
-e TOOL_FIND_DESCRIPTION="Search for relevant code snippets using natural language." \
-- uvx mcp-server-qdrant
Для Cursor и Windsurf в README рекомендуют SSE-транспорт: он поддерживает удалённые подключения, поэтому сервер легко расшарить на команду или вынести в облако. В настройках редактора вы указываете адрес работающего сервера.
Как проверить, что всё работает. Первый критерий — сервер стартовал без ошибок и в логах нет жалоб на подключение к Qdrant. Второй — клиент видит два инструмента, qdrant-store и qdrant-find, в списке доступных. Третий — учебный прогон: попросите агента сохранить короткую заметку, затем в новом диалоге попросите её найти по смыслу, не повторяя точных слов. Если запись нашлась, цепочка «клиент → сервер → Qdrant» собрана верно.
Полезно заранее разобраться, как устроен поиск по смыслу — этому посвящён материал Эмбеддинги: что это простыми словами. А общая схема, частью которой становится MCP-сервер, разобрана в статье RAG в ИИ: что это и где схема ломается.
Смежные варианты: uvx, Docker, Smithery и выбор по задаче
Одна и та же задача решается четырьмя путями, и выбор зависит от того, где живёт клиент и кто ещё будет пользоваться сервером.
| Способ | Когда подходит | Что учесть |
|---|---|---|
| uvx | Локальный клиент на той же машине | Отдельная установка не нужна |
| Docker | Изоляция, перенос между машинами | Нужен FASTMCP_SERVER_HOST="0.0.0.0" |
| Smithery | Быстрый старт в Claude Desktop | Прописывает конфигурацию автоматически |
| Ручная правка конфига | Нестандартный клиент | Нужен блок в mcpServers |
Транспорт выбирается по той же логике. stdio подходит локальным MCP-клиентам и стоит по умолчанию. SSE нужен, когда клиент удалённый или сервер обслуживает несколько человек: он слушает порт и принимает входящие соединения.
Отдельный слой — настройка под конкретную задачу. Через описания инструментов сервер превращается в специализированный поисковик по коду: в README показано, как переопределить TOOL_STORE_DESCRIPTION и TOOL_FIND_DESCRIPTION под хранение сниппетов. В блоге Qdrant ту же механику применяют шире — под любую задачу семантического поиска, где важен контекст.
Есть и вариант с наследованием: сервер представлен классом QdrantMCPServer, от которого можно строить проектные серверы со своей логикой. Это путь для тех, кому стандартных двух инструментов мало.
Если вы собираете интерфейс для работы с моделью, пригодится разбор Open WebUI: что это, как установить и настроить.
Типичные проблемы и способы диагностики
Большинство сбоев сводится к четырём причинам, и каждая проверяется отдельно.
Сервер не видит Qdrant. Симптом — ошибки подключения при старте. Проверка: откройте QDRANT_URL в браузере или curl с той же машины, где запущен сервер. Если Qdrant в контейнере, localhost внутри контейнера указывает на сам контейнер; используйте имя сервиса в сети Docker.
Клиент не видит инструменты. Симптом — сервер запущен, но в списке инструментов пусто. Проверка: совпадает ли транспорт. Клиент, настроенный на stdio, не подключится к серверу, поднятому с --transport sse, и наоборот. Для SSE убедитесь, что порт совпадает с FASTMCP_SERVER_PORT.
Контейнер недоступен снаружи. Симптом — внутри Docker всё работает, снаружи соединение отклоняется. Причина в адресе привязки: по умолчанию FASTMCP_SERVER_HOST равен 127.0.0.1, и в контейнере это значит «только внутри». Выставьте 0.0.0.0, как советует README.
Конфликты зависимостей. В релизах проекта отдельно отмечают правки совместимости с fastmcp и pydantic, включая закрепление версии pydantic для обхода несовместимостей. Если после обновления сервер падает, проверьте версии этих пакетов и сверьтесь со страницей релизов.
Полезная привычка — включать FASTMCP_SERVER_DEBUG на время отладки. Переменные FASTMCP_SERVER_ON_DUPLICATE_TOOLS, FASTMCP_SERVER_ON_DUPLICATE_PROMPTS и FASTMCP_SERVER_ON_DUPLICATE_RESOURCES управляют поведением при дублирующихся элементах и по умолчанию лишь предупреждают.
Частые вопросы
Как настроить MCP-сервер Qdrant с нуля?
Поднимите Qdrant, задайте QDRANT_URL, COLLECTION_NAME и EMBEDDING_MODEL, затем запустите uvx mcp-server-qdrant. Транспорт по умолчанию — stdio, он годится для локального клиента. Дальше добавьте сервер в конфигурацию клиента: вручную или командой Smithery.
Какие переменные окружения обязательны?
Для показанного сетевого сценария задайте QDRANT_URL и COLLECTION_NAME. Альтернативный локальный режим использует QDRANT_LOCAL_PATH. Модель эмбеддингов имеет значение по умолчанию; QDRANT_API_KEY нужен для базы с авторизацией.
Чем отличается stdio от SSE?
stdio работает через стандартный ввод-вывод и подходит локальным MCP-клиентам. SSE слушает порт и принимает входящие соединения, что удобно для удалённых клиентов и командной работы. Переключение — флагом --transport.
Почему сервер не подключается к Qdrant в Docker?
Для соединения MCP-сервера с базой проверьте QDRANT_URL, API-ключ и сетевую доступность Qdrant из контейнера. Имя сервиса в сети Docker позволяет обратиться к другому контейнеру. Параметр FASTMCP_SERVER_HOST="0.0.0.0" нужен для входящих HTTP-подключений клиента к самому MCP-серверу.
Как проверить, что подключение работает?
Убедитесь, что клиент видит инструменты qdrant-store и qdrant-find. Затем сохраните тестовую заметку и найдите её в новом диалоге по смыслу, не повторяя точных формулировок. Если запись вернулась, вся цепочка собрана правильно.