Qdrant MCP Server

официальный

Семантический поиск с использованием векторной базы данных Qdrant.

GitHub
1.4k

Документация

mcp-server-qdrant: Сервер Qdrant MCP

smithery badge

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

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

Обзор

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

Компоненты

Инструменты

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

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

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

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

ИмяОписаниеЗначение по умолчанию
QDRANT_URLURL сервера QdrantНет
QDRANT_API_KEYAPI-ключ для сервера QdrantНет
COLLECTION_NAMEИмя коллекции по умолчанию.Нет
QDRANT_LOCAL_PATHПуть к локальной базе данных Qdrant (альтернатива QDRANT_URL)Нет
EMBEDDING_PROVIDERИспользуемый провайдер эмбеддингов (пока поддерживается только "fastembed")fastembed
EMBEDDING_MODELИмя используемой модели эмбеддинговsentence-transformers/all-MiniLM-L6-v2
TOOL_STORE_DESCRIPTIONПользовательское описание для инструмента сохраненияСм. значение по умолчанию в settings.py
TOOL_FIND_DESCRIPTIONПользовательское описание для инструмента поискаСм. значение по умолчанию в 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_SERVER_DEBUGВключить режим отладкиfalse
FASTMCP_SERVER_HOSTАдрес хоста для привязки сервера127.0.0.1
FASTMCP_SERVER_PORTПорт для запуска сервера8000
FASTMCP_SERVER_ON_DUPLICATE_RESOURCESПоведение при дублировании ресурсов (warn, error, replace, ignore)warn
FASTMCP_SERVER_ON_DUPLICATE_TOOLSПоведение при дублировании инструментов (warn, error, replace, ignore)warn
FASTMCP_SERVER_ON_DUPLICATE_PROMPTSПоведение при дублировании промптов (warn, error, replace, ignore)warn
FASTMCP_SERVER_DEPENDENCIESСписок зависимостей для установки в окружении сервера[]

[!NOTE] Специфичные для сервера настройки используют префикс FASTMCP_SERVER_. Это может измениться в будущих версиях.

Установка

Использование 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: Потоковый HTTP-транспорт, идеально подходит для удаленных клиентов, более современный, чем SSE

Если не указано иное, транспортом по умолчанию является stdio.

При использовании транспорта 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

Для сборки и запуска сервера MCP доступен Dockerfile:

# Build the container
docker build -t mcp-server-qdrant .

# Run the container
docker run -p 8000:8000 \
  -e FASTMCP_SERVER_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_SERVER_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, поскольку он поддерживает удаленные соединения. Это упрощает совместное использование сервера с командой или его использование в облачной среде.

Эта конфигурация превращает сервер Qdrant MCP в специализированный инструмент поиска по коду, который может:

  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 в вашем браузере.

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 — это инструмент разработчика для тестирования и отладки серверов MCP. Он запускает как клиентский интерфейс (порт по умолчанию 5173), так и прокси-сервер MCP (порт по умолчанию 3000). Откройте клиентский интерфейс в вашем браузере, чтобы использовать инспектор.

QDRANT_URL=":memory:" COLLECTION_NAME="test" \
fastmcp dev src/mcp_server_qdrant/server.py

После запуска откройте браузер по адресу http://localhost:5173, чтобы получить доступ к интерфейсу инспектора.

Лицензия

Этот MCP-сервер лицензирован под лицензией Apache License 2.0. Это означает, что вы можете свободно использовать, изменять и распространять программное обеспечение в соответствии с условиями лицензии Apache License 2.0. Для получения дополнительной информации ознакомьтесь с файлом LICENSE в репозитории проекта.