qdrant-mcp-ollama

Сервер Model Context Protocol (MCP) для векторной базы данных Qdrant, использующий Ollama для GPU-ускоренных эмбеддингов.

Почему не официальный mcp-server-qdrant?

Официальный MCP-сервер Qdrant использует FastEmbed для эмбеддингов, которые:

• Работают только на CPU — медленно на больших кодовых базах, не задействуют современные GPU

• Используют маленькую модель (all-MiniLM-L6-v2, 384-dim) — менее качественные эмбеддинги

• Однопроцессная блокировка в локальном режиме — только один MCP-клиент может одновременно обращаться к базе данных

Этот сервер решает все три проблемы:

Related MCP server: Claude Context MCP

Архитектура

┌──────────────┐     ┌────────────────────┐     ┌─────────────┐
│  MCP Client   │────>│  qdrant-mcp-ollama │────>│   Ollama    │
│ (Claude Code, │     │    (server.py)      │     │  (GPU)      │
│  Kilo Code,   │<────│                    │     └─────────────┘
│  Cursor, etc) │     └────────┬───────────┘
└──────────────┘              │
                              v
                   ┌────────────────────┐
                   │   Qdrant Server    │
                   │  (Docker, :6333)   │
                   │  Storage: local    │
                   │  disk / cloud      │
                   └────────────────────┘

Предварительные требования

• Ollama — установлена и запущена, эмбеддинг-модель скачана

• Docker — для запуска сервера Qdrant

• uv — менеджер пакетов Python (рекомендуется) или pip

Быстрый старт

1. Скачайте эмбеддинг-модель в Ollama

ollama pull bge-m3

2. Запустите сервер Qdrant

docker run -d --name qdrant-server \
  -p 6333:6333 -p 6334:6334 \
  -v qdrant-storage:/qdrant/storage \
  --restart unless-stopped \
  qdrant/qdrant:latest

3. Запустите MCP-сервер

# No install needed — uv downloads dependencies on-the-fly:
QDRANT_URL="http://localhost:6333" \
EMBEDDING_MODEL="bge-m3" \
uv run --with fastmcp --with qdrant-client --with httpx python server.py

4. Индексируйте кодовую базу

uv run --with qdrant-client --with httpx python embed_codebase.py \
  /path/to/your/project my-project --preset python

5. Поиск через вашего MCP-клиента

После настройки (см. разделы ниже) спросите вашего ИИ-ассистента:

"Найди в кодовой базе логику аутентификации"

Он использует инструмент qdrant_find, чтобы вернуть семантически релевантные фрагменты кода.

Настройка сервера Qdrant

Вариант A: Docker (рекомендуется)

Храните данные на отдельном диске (например, E: в Windows):

# Create storage directories
mkdir -p E:/qdrant-storage E:/qdrant-snapshots

# Start Qdrant with persistent storage
docker run -d --name qdrant-server \
  -p 6333:6333 -p 6334:6334 \
  -v E:/qdrant-storage:/qdrant/storage \
  -v E:/qdrant-snapshots:/qdrant/snapshots \
  --restart unless-stopped \
  qdrant/qdrant:latest

На Linux/macOS:

docker run -d --name qdrant-server \
  -p 6333:6333 -p 6334:6334 \
  -v ~/qdrant-storage:/qdrant/storage \
  --restart unless-stopped \
  qdrant/qdrant:latest

Флаг --restart unless-stopped гарантирует, что Qdrant запускается автоматически вместе с Docker Desktop.

Проверьте, что он запущен:

docker ps --filter name=qdrant-server
# Or open http://localhost:6333/dashboard in your browser

Вариант B: Qdrant Cloud

Зарегистрируйтесь на cloud.qdrant.io и получите URL и API-ключ. Затем укажите их:

QDRANT_URL="https://your-cluster.cloud.qdrant.io:6333"
QDRANT_API_KEY="your-api-key"

Примечание: Переменная окружения QDRANT_API_KEY автоматически передаётся клиенту Qdrant.

Эмбеддинг кодовой базы

Скрипт embed_codebase.py сканирует каталог, разбивает исходные файлы на фрагменты и массово индексирует их в Qdrant, используя Ollama на GPU.

Базовое использование

uv run --with qdrant-client --with httpx python embed_codebase.py <directory> <collection-name>

Использование пресетов расширений

# Python project
python embed_codebase.py ./my-api api-backend --preset python

# Full-stack web project
python embed_codebase.py ./my-app frontend --preset web

# R / bioinformatics project
python embed_codebase.py ./analysis bio-analysis --preset r

# Everything
python embed_codebase.py ./mono-repo all-code --preset all

Пользовательские расширения

python embed_codebase.py ./project my-collection --extensions .py .sql .sh .yaml

Доступные пресеты

Если не указаны --preset или --extensions, скрипт определяет типы файлов автоматически.

Все параметры

usage: embed_codebase.py <directory> <collection> [options]

positional arguments:
  directory              Path to the codebase directory
  collection             Qdrant collection name

options:
  --extensions EXT [EXT ...]  File extensions to include (e.g. .py .ts)
  --preset PRESET             Use a preset group of extensions
  --model MODEL               Ollama embedding model (default: bge-m3)
  --qdrant-url URL            Qdrant server URL (default: http://localhost:6333)
  --ollama-url URL            Ollama server URL (default: http://localhost:11434)
  --chunk-size N              Max lines per chunk (default: 80)
  --chunk-overlap N           Overlap lines between chunks (default: 10)
  --batch-size N              Upload batch size for Qdrant (default: 500)
  --append                    Append to existing collection instead of replacing

Режим дополнения

По умолчанию повторный запуск скрипта заменяет коллекцию. Используйте --append, чтобы добавить данные в существующую коллекцию:

# First embed
python embed_codebase.py ./src main-code --preset typescript

# Add more files later
python embed_codebase.py ./docs main-code --extensions .md --append

Использование нескольких кодовых баз

Используйте отдельные коллекции для каждой кодовой базы, чтобы результаты поиска были релевантными и не смешивались:

# Project A
python embed_codebase.py ~/projects/api-server api-server --preset python

# Project B
python embed_codebase.py ~/projects/web-app web-app --preset web

# Project C
python embed_codebase.py ~/projects/data-pipeline data-pipeline --preset python

При настройке MCP-сервера:

• Без COLLECTION_NAME: коллекцию необходимо указывать при каждом запросе. Идеально, когда один MCP-сервер обслуживает несколько проектов.

• С COLLECTION_NAME: коллекция по умолчанию используется автоматически. Задавайте её отдельно для каждого проекта, если ваш MCP-клиент поддерживает конфигурацию в рамках проекта.

Настройка Claude Code

Добавление MCP-сервера

claude mcp add qdrant -s user \
  -e QDRANT_URL="http://localhost:6333" \
  -e OLLAMA_URL="http://localhost:11434" \
  -e EMBEDDING_MODEL="bge-m3" \
  -- uv run --with fastmcp --with qdrant-client --with httpx \
     python /path/to/qdrant-mcp-ollama/server.py

Замените /path/to/qdrant-mcp-ollama/ на фактический путь, куда вы клонировали этот репозиторий.

С коллекцией по умолчанию

Если вы работаете преимущественно с одним проектом:

claude mcp add qdrant -s user \
  -e QDRANT_URL="http://localhost:6333" \
  -e OLLAMA_URL="http://localhost:11434" \
  -e EMBEDDING_MODEL="bge-m3" \
  -e COLLECTION_NAME="my-project" \
  -- uv run --with fastmcp --with qdrant-client --with httpx \
     python /path/to/qdrant-mcp-ollama/server.py

Проверка

claude mcp list
# Should show: qdrant: ... ✓ Connected

claude mcp get qdrant
# Shows full configuration details

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

После настройки Claude Code сможет использовать такие инструменты:

• qdrant_store — сохранить информацию: "Сохрани этот паттерн аутентификации в Qdrant"

• qdrant_find — поиск: "Найди код, связанный с миграциями базы данных"

Для конфигураций с несколькими коллекциями (без коллекции по умолчанию) указывайте коллекцию явно:

"Найди в коллекции api-server логику ограничения частоты запросов"

Настройка Kilo Code (расширение VS Code)

Kilo Code — расширение VS Code со встроенной поддержкой MCP.

Вариант 1: Настройка MCP вручную

1. Откройте настройки Kilo Code в VS Code.

2. Перейдите к конфигурации MCP-серверов.

3. Добавьте новый сервер со следующими параметрами:

4. Задайте переменные окружения:

Вариант 2: settings.json в VS Code

Добавьте в ваш файл settings.json в VS Code (Ctrl+Shift+P > Preferences: Open User Settings (JSON)):

{
  "kilocode.mcpServers": {
    "qdrant": {
      "command": "uv",
      "args": [
        "run", "--with", "fastmcp", "--with", "qdrant-client", "--with", "httpx",
        "python", "/path/to/qdrant-mcp-ollama/server.py"
      ],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "OLLAMA_URL": "http://localhost:11434",
        "EMBEDDING_MODEL": "bge-m3",
        "COLLECTION_NAME": "my-project"
      }
    }
  }
}

Настройка на уровне проекта в Kilo Code

Для конфигураций с несколькими кодовыми базами настройте Kilo Code на уровне проекта (не глобально), указав COLLECTION_NAME для конкретного проекта. Так каждая рабочая область будет искать только в своей кодовой базе.

Настройка других MCP-клиентов

Cursor / Windsurf

Запустите сервер с транспортом SSE для клиентов с удалённым доступом:

QDRANT_URL="http://localhost:6333" \
OLLAMA_URL="http://localhost:11434" \
EMBEDDING_MODEL="bge-m3" \
FASTMCP_PORT=8000 \
uv run --with fastmcp --with qdrant-client --with httpx \
  python server.py --transport sse

Затем в настройках MCP в Cursor/Windsurf подключитесь к адресу: http://localhost:8000/sse

Стандартный MCP-клиент (stdio)

Транспорт по умолчанию — stdio. Любой MCP-клиент с поддержкой stdio может использовать этот сервер, запустив команду:

uv run --with fastmcp --with qdrant-client --with httpx python server.py

Справочник по конфигурации

Переменные окружения MCP-сервера

Выбор эмбеддинг-модели

Все модели ниже доступны через ollama pull <model>:

Рекомендация: Начните с bge-m3. Она хорошо работает с кодом, поддерживает многоязычный контент (комментарии на любом языке) и балансирует между качеством и скоростью.

Важно: Эмбеддинг-модель, использованная для индексации коллекции, должна совпадать с моделью, используемой для запросов. Если вы переиндексируете с другой моделью, удалите и создайте коллекцию заново.

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

Более крупные модели занимают больше GPU. Если GPU недогружен:

• Перейдите с nomic-embed-text (274 MB) на bge-m3 (1.2 GB) или более крупную модель.

• Скрипт эмбеддинга отправляет все тексты одним пакетом, чтобы максимально нагрузить GPU.

• При отдельных запросах (через qdrant_find) нагрузка на GPU кратковременна — это нормально, эмбеддинг одиночного запроса занимает миллисекунды.

Проверьте использование GPU: nvidia-smi (NVIDIA) или rocm-smi (AMD).

Инструменты MCP

qdrant_store

Сохраняет информацию в базе данных Qdrant.

qdrant_find

Выполняет поиск релевантной информации с использованием семантической близости.

Устранение неполадок

«Connection closed» / MCP-сервер не запускается

• Запущен ли Ollama? Проверьте командой ollama list. При необходимости запустите с помощью ollama serve.

• Загружена ли эмбеддинг-модель? Выполните ollama pull bge-m3.

• Запущен ли Qdrant? Проверьте командой docker ps --filter name=qdrant-server.

Ошибка «Collection does not exist»

Коллекция создаётся скриптом эмбеддинга или при первом вызове qdrant_store. Выполните одно из действий:

• Запустите embed_codebase.py, чтобы сначала проиндексировать кодовую базу.

• Или сохраните что-нибудь через qdrant_store, чтобы коллекция создалась автоматически.

Ошибки несовпадения размерности

Это происходит, когда коллекция была создана с одной эмбеддинг-моделью, а запрос выполняется другой. Исправление:

1. Удалите коллекцию: откройте http://localhost:6333/dashboard.

2. Заново выполните эмбеддинг с правильной моделью.

3. Убедитесь, что EMBEDDING_MODEL в конфигурации MCP-сервера совпадает с той, что использовалась для эмбеддинга.

Ошибка «Storage folder is already accessed by another instance»

Эта ошибка возникает в официальном mcp-server-qdrant при использовании локального режима (QDRANT_LOCAL_PATH). Данный проект избегает эту ошибку, подключаясь к серверу Qdrant по URL. Убедитесь, что оба сервера не используют один локальный путь.

Медленный эмбеддинг / низкая загрузка GPU

• Используйте более крупную модель: bge-m3 (1.2 ГБ) вместо nomic-embed-text (274 МБ)

• Скрипт эмбеддинга отправляет все тексты одним пакетом — если у вас тысячи фрагментов, это максимизирует загрузку GPU

• Для очень больших кодовых баз (10 000+ файлов) рассмотрите возможность разбиения на несколько запусков по каталогам

Лицензия

Apache License 2.0 — см. LICENSE.