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

smithery badge

Model Context Protocol (MCP) — это открытый протокол, обеспечивающий бесшовную интеграцию приложений на основе LLM с внешними источниками данных и инструментами. Создаёте ли вы IDE с поддержкой ИИ, расширяете интерфейс чата или разрабатываете собственные рабочие процессы с ИИ, MCP предоставляет стандартизированный способ подключить LLM к необходимому контексту.

Этот репозиторий — пример создания MCP-сервера для Qdrant, векторной поисковой системы.

Обзор

Официальный сервер Model Context Protocol для хранения и извлечения воспоминаний в векторной поисковой системе Qdrant. Он служит слоем семантической памяти поверх базы данных Qdrant.

Компоненты

Инструменты

  1. qdrant-store
    • Сохранить информацию в базе данных Qdrant
    • Входные данные:
      • information (string): информация для сохранения
      • metadata (JSON): необязательные метаданные для сохранения
      • collection_name (string): имя коллекции, в которой нужно сохранить информацию. Это поле обязательно, если имя коллекции по умолчанию не задано. Если имя коллекции по умолчанию задано, это поле недоступно.
    • Возвращает: сообщение с подтверждением
  2. qdrant-find
    • Извлечь релевантную информацию из базы данных Qdrant
    • Входные данные:
      • query (string): запрос для поиска
      • collection_name (string): имя коллекции, в которой нужно сохранить информацию. Это поле обязательно, если имя коллекции по умолчанию не задано. Если имя коллекции по умолчанию задано, это поле недоступно.
    • Возвращает: информацию, сохранённую в базе данных Qdrant, в виде отдельных сообщений

Переменные окружения

Настройка выполняется с помощью переменных окружения. Единственный аргумент командной строки — --transport, который используется для выбора транспортного протокола.

[!NOTE] Нельзя одновременно указывать QDRANT_URL и QDRANT_LOCAL_PATH.

ИмяОписаниеЗначение по умолчанию
QDRANT_URLURL-адрес сервера QdrantNone
QDRANT_API_KEYКлюч API сервера QdrantNone
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 в специализированный инструмент поиска по коду, который может:

  1. Сохранять фрагменты кода, документацию и сведения о реализации
  2. Находить релевантные примеры кода с помощью семантического поиска
  3. Помогать разработчикам находить конкретные реализации или шаблоны использования

Можно заполнить базу данных, сохраняя описания фрагментов кода на естественном языке (в параметре information) вместе с самим кодом (в свойстве metadata.code), а затем искать их с помощью запросов на естественном языке, описывающих нужные результаты.

[!NOTE] Приведённые выше описания инструментов — это примеры, которые может потребоваться адаптировать под конкретный сценарий использования. Подумайте о том, чтобы изменить описания в соответствии с рабочими процессами вашей команды и типами фрагментов кода, которые вы хотите сохранять и находить.

Если вы успешно установили mcp-server-qdrant, но он по-прежнему не работает с Cursor, попробуйте создать правила Cursor, чтобы MCP-инструменты всегда использовались, когда агент создаёт новый фрагмент кода. Можно ограничить правила определёнными типами файлов, чтобы MCP-сервер не использовался для документации и других типов содержимого.

Использование с Claude Code

Расширьте возможности Claude Code, подключив его к этому MCP-серверу и включив семантический поиск по существующей кодовой базе.

Настройка mcp-server-qdrant

  1. Добавьте 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
    
  2. Убедитесь, что сервер добавлен:

    claude mcp list
    

Семантический поиск по коду в Claude Code

Описания инструментов, заданные в TOOL_STORE_DESCRIPTION и TOOL_FIND_DESCRIPTION, указывают Claude Code, как использовать MCP-сервер. Приведённые выше описания — это примеры, которые может потребоваться адаптировать под конкретный сценарий использования. Однако Claude Code уже должен уметь:

  1. Использовать инструмент qdrant-store для сохранения фрагментов кода с описаниями.
  2. Использовать инструмент qdrant-find для поиска релевантных фрагментов кода с помощью запросов на естественном языке.

Запуск MCP-сервера в режиме разработки

MCP-сервер можно запустить в режиме разработки с помощью команды mcp dev. Она запустит сервер и откроет MCP Inspector в браузере.

COLLECTION_NAME=mcp-dev fastmcp dev src/mcp_server_qdrant/server.py

Использование с VS Code

Чтобы установить сервер одним нажатием, нажмите одну из кнопок установки ниже:

Install with UVX in VS Code Install with UVX in VS Code Insiders

Install with Docker in VS Code Install with Docker in VS Code Insiders

Ручная установка

Добавьте следующий блок 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 в репозитории проекта.

Конфиденциальность и поддержка