mcp-server-qdrant: Сервер Qdrant для MCP

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

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

Обзор

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

Компоненты

Инструменты

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

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

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

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

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

Поскольку mcp-server-qdrant основан на FastMCP, он также поддерживает все переменные окружения FastMCP. Наиболее важные из них перечислены ниже:

[!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

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

# 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, которые имеют встроенную поддержку Протокола контекста модели.

Использование с 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:

   ```shell

   Добавьте mcp-server-qdrant, настроенный для поиска кода

   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="Сохраняйте фрагменты кода с описаниями. Параметр 'information' должен содержать описание на естественном языке того, что делает код, тогда как сам код должен быть включён в параметр 'metadata' как свойство 'code'." \ -e TOOL_FIND_DESCRIPTION="Ищите релевантные фрагменты кода с помощью естественного языка. Параметр 'query' должен описывать функциональность, которую вы ищете." \ -- uvx mcp-server-qdrant ```

2. Проверьте, что сервер добавлен:

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

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