Qdrant MCP

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

Model Context Protocol (MCP) — это открытый протокол, который обеспечивает бесшовную интеграцию между LLM-приложениями и внешними источниками данных и инструментами. Создаете ли вы IDE на основе ИИ, улучшаете чат-интерфейс или создаете пользовательские AI-рабочие процессы, 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.

Name	Description	Default Value
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. Наиболее важные из них перечислены ниже:

Environment Variable	Description	Default Value
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: Транспорт Streamable 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

Для установки в один клик нажмите одну из кнопок установки ниже:

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

Добавьте следующий JSON-блок в файл User Settings (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). Откройте клиентский интерфейс в вашем браузере, чтобы использовать инспектор.

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 в репозитории проекта.

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

• Политика конфиденциальности
• Поддержка