Qdrant MCP Server

Сервер протокола контекста модели (MCP), предоставляющий возможности семантического поиска с использованием векторной базы данных Qdrant и различных провайдеров эмбеддингов.

Возможности

• Без настройки: Работает «из коробки» с Ollama — ключи API не требуются

• Приоритет конфиденциальности: Локальные эмбеддинги и векторное хранилище — данные никогда не покидают ваш компьютер

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

• Поиск по истории Git: Индексация истории коммитов для семантического поиска по прошлым изменениям, исправлениям и паттернам

• Расширенный поиск: Контекстный поиск (код + git с корреляциями) и федеративный поиск по нескольким репозиториям

• Несколько провайдеров: Ollama (по умолчанию), OpenAI, Cohere и Voyage AI

• Гибридный поиск: Комбинирование семантического и ключевого поиска для получения лучших результатов

• Семантический поиск: Поиск на естественном языке с фильтрацией по метаданным

• Инкрементальная индексация: Эффективные обновления — повторно индексируются только измененные файлы

• Настраиваемые промпты: Создание пользовательских промптов для направленных рабочих процессов без изменения кода

• Ограничение частоты запросов (Rate Limiting): Интеллектуальное регулирование с экспоненциальной задержкой

• Полный CRUD: Создание, поиск и управление коллекциями и документами

• Структурированное логирование: Логирование в формате JSON через Pino с настраиваемыми уровнями логирования

• Гибкое развертывание: Запуск локально (stdio) или как удаленный HTTP-сервер

• Аутентификация по ключу API: Подключение к защищенным экземплярам Qdrant (Qdrant Cloud, self-hosted с ключами API)

Related MCP server: MCP Qdrant Server with OpenAI Embeddings

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

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

• Node.js 22.x или 24.x

• Podman или Docker с поддержкой Compose

Установка

# Clone and install
git clone https://github.com/mhalder/qdrant-mcp-server.git
cd qdrant-mcp-server

# Node 22.x
npm install

# Node 24.x (requires C++20 flag for native module compilation)
CXXFLAGS='-std=c++20' npm install

# Start services (choose one)
podman compose up -d   # Using Podman
docker compose up -d   # Using Docker

# Pull the embedding model
podman exec ollama ollama pull nomic-embed-text  # Podman
docker exec ollama ollama pull nomic-embed-text  # Docker

# Build
npm run build

Конфигурация

Локальная настройка (транспорт stdio)

claude mcp add --transport stdio qdrant -- node /path/to/qdrant-mcp-server/build/index.js

Или добавьте в ~/.claude.json:

{
  "mcpServers": {
    "qdrant": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/qdrant-mcp-server/build/index.js"]
    }
  }
}

Для Qdrant Cloud или защищенных экземпляров добавьте --env QDRANT_API_KEY=your-key или установите в конфигурации окружения.

Попробуйте:

Create a collection called "notes" and add a document about machine learning

Включите примеры промптов: Скопируйте prompts.example.json в prompts.json и перезапустите. Используйте /prompt для вывода списка доступных промптов.

Удаленная настройка (транспорт HTTP)

⚠️ Предупреждение о безопасности: При развертывании HTTP-транспорта в продакшене:

• Всегда запускайте за обратным прокси-сервером (nginx, Caddy) с HTTPS

• Реализуйте аутентификацию/авторизацию на уровне прокси

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

• Никогда не открывайте доступ напрямую в публичный интернет без защиты

• Рассмотрите возможность реализации ограничения частоты запросов на уровне прокси

• Мониторьте логи сервера на предмет подозрительной активности

Запуск сервера:

TRANSPORT_MODE=http HTTP_PORT=3000 node build/index.js

Вариант 1: Использование claude mcp add

claude mcp add --transport http qdrant http://your-server:3000/mcp

Вариант 2: Добавление в ~/.claude.json

{
  "mcpServers": {
    "qdrant": {
      "type": "http",
      "url": "http://your-server:3000/mcp"
    }
  }
}

Использование другого провайдера:

"env": {
  "EMBEDDING_PROVIDER": "openai",  // or "cohere", "voyage"
  "OPENAI_API_KEY": "sk-...",      // provider-specific API key
  "QDRANT_URL": "http://localhost:6333"
}

Перезапустите после внесения изменений.

См. раздел Расширенная конфигурация ниже для получения информации обо всех параметрах.

Инструменты

Управление коллекциями

Операции с документами

Векторизация кода

История Git

Расширенный поиск

Ресурсы

• qdrant://collections - Список всех коллекций

• qdrant://collection/{name} - Детали коллекции

Настраиваемые промпты

Создавайте пользовательские промпты, адаптированные к вашим конкретным задачам, без изменения кода. Промпты обеспечивают направленные рабочие процессы для типичных задач.

Примечание: По умолчанию сервер ищет prompts.json в корневом каталоге проекта. Если файл существует, промпты загружаются автоматически. Вы можете указать собственный путь с помощью переменной окружения PROMPTS_CONFIG_FILE.

Настройка

1. Создайте файл конфигурации промптов (например, prompts.json в корне проекта):

   См. prompts.example.json для примеров конфигураций, которые можно скопировать и настроить.

2. Настройте сервер (опционально — нужно только для пользовательского пути):

Если вы разместите prompts.json в корне проекта, дополнительная настройка не требуется. Чтобы использовать собственный путь:

{
  "mcpServers": {
    "qdrant": {
      "command": "node",
      "args": ["/path/to/qdrant-mcp-server/build/index.js"],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "PROMPTS_CONFIG_FILE": "/custom/path/to/prompts.json"
      }
    }
  }
}

3. Используйте промпты в своем ИИ-ассистенте:

Claude Code:

/mcp__qdrant__find_similar_docs papers "neural networks" 10

VSCode:

/mcp.qdrant.find_similar_docs papers "neural networks" 10

Примеры промптов

См. prompts.example.json для готовых к использованию промптов, включая:

• setup_rag_collection - Создание коллекций, оптимизированных для RAG

• analyze_and_optimize - Аналитика и рекомендации по коллекциям

• compare_search_strategies - Сравнение семантического и гибридного поиска

• migrate_to_hybrid - Руководство по миграции коллекции

• debug_search_quality - Устранение неполадок с низким качеством поиска

• build_knowledge_base - Структурированная документация с метаданными

• index_git_history - Индексация истории коммитов репозитория для семантического поиска

• search_project_history - Поиск по истории git для понимания реализации функций

• investigate_code_with_history - Глубокое погружение в код с контекстным поиском

• cross_repo_search - Поиск паттернов по нескольким репозиториям

• trace_feature_evolution - Отслеживание эволюции функций во времени

• security_audit_search - Поиск кода и исправлений, связанных с безопасностью

Синтаксис шаблонов

Шаблоны используют плейсхолдеры {{variable}}:

• Обязательные аргументы должны быть предоставлены

• Необязательные аргументы используют значения по умолчанию, если не указаны

• Неизвестные переменные остаются в выводе как есть

Векторизация кода

Интеллектуально индексируйте и ищите по своей кодовой базе с помощью семантического поиска кода. Идеально подходит для разработки с поддержкой ИИ, исследования кода и понимания больших кодовых баз.

Возможности

• Разбиение с учетом AST: Интеллектуальное разделение кода на границах функций/классов с использованием tree-sitter

• Поддержка нескольких языков: 35+ типов файлов, включая TypeScript, Python, Java, Go, Rust, C++, и другие

• Инкрементальные обновления: Повторная индексация только измененных файлов для быстрых обновлений

• Умные паттерны игнорирования: Учитывает файлы .gitignore, .dockerignore и пользовательские файлы .contextignore

• Семантический поиск: Запросы на естественном языке для поиска релевантного кода

• Фильтрация по метаданным: Фильтрация по типу файла, паттернам путей или языку

• Локальный приоритет: Вся обработка происходит локально — ваш код никогда не покидает ваш компьютер

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

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

# Via Claude Code MCP tool
/mcp__qdrant__index_codebase /path/to/your/project

2. Ищите по своему коду:

# Natural language search
/mcp__qdrant__search_code /path/to/your/project "authentication middleware"

# Filter by file type
/mcp__qdrant__search_code /path/to/your/project "database schema" --fileTypes .ts,.js

# Filter by path pattern
/mcp__qdrant__search_code /path/to/your/project "API endpoints" --pathPattern src/api/**

3. Обновляйте после изменений:

# Incrementally re-index only changed files
/mcp__qdrant__reindex_changes /path/to/your/project

Примеры использования

Индексация проекта на TypeScript

// The MCP tool automatically:
// 1. Scans all .ts, .tsx, .js, .jsx files
// 2. Respects .gitignore patterns (skips node_modules, dist, etc.)
// 3. Chunks code at function/class boundaries
// 4. Generates embeddings using your configured provider
// 5. Stores in Qdrant with metadata (file path, line numbers, language)

index_codebase({
  path: "/workspace/my-app",
  forceReindex: false, // Set to true to re-index from scratch
});

// Output:
// ✓ Indexed 247 files (1,823 chunks) in 45.2s

Поиск кода аутентификации

search_code({
  path: "/workspace/my-app",
  query: "how does user authentication work?",
  limit: 5,
});

// Results include file path, line numbers, and code snippets:
// [
//   {
//     filePath: "src/auth/middleware.ts",
//     startLine: 15,
//     endLine: 42,
//     content: "export async function authenticateUser(req: Request) { ... }",
//     score: 0.89,
//     language: "typescript"
//   },
//   ...
// ]

Поиск с фильтрами

// Only search TypeScript files
search_code({
  path: "/workspace/my-app",
  query: "error handling patterns",
  fileTypes: [".ts", ".tsx"],
  limit: 10,
});

// Only search in specific directories
search_code({
  path: "/workspace/my-app",
  query: "API route handlers",
  pathPattern: "src/api/**",
  limit: 10,
});

Инкрементальная переиндексация

// After making changes to your codebase
reindex_changes({
  path: "/workspace/my-app",
});

// Output:
// ✓ Updated: +3 files added, ~5 files modified, -1 files deleted
// ✓ Chunks: +47 added, -23 deleted in 8.3s

Проверка статуса индексации

get_index_status({
  path: "/workspace/my-app",
});

// Output:
// {
//   status: "indexed",      // "not_indexed" | "indexing" | "indexed"
//   isIndexed: true,        // deprecated: use status instead
//   collectionName: "code_a3f8d2e1",
//   chunksCount: 1823,
//   filesCount: 247,
//   lastUpdated: "2025-01-30T10:15:00Z",
//   languages: ["typescript", "javascript", "json"]
// }

Поддерживаемые языки

Языки программирования (35+ типов файлов):

• Web: TypeScript, JavaScript, Vue, Svelte

• Backend: Python, Java, Go, Rust, Ruby, PHP

• Systems: C, C++, C#

• Mobile: Swift, Kotlin, Dart

• Functional: Scala, Clojure, Haskell, OCaml

• Scripting: Bash, Shell, Fish

• Data: SQL, GraphQL, Protocol Buffers

• Config: JSON, YAML, TOML, XML, Markdown

См. конфигурацию для получения полного списка и параметров настройки.

Пользовательские паттерны игнорирования

Создайте файл .contextignore в корне проекта, чтобы указать дополнительные паттерны для игнорирования:

# .contextignore
**/test/**
**/*.test.ts
**/*.spec.ts
**/fixtures/**
**/mocks/**
**/__tests__/**

Лучшие практики

1. Индексируйте один раз, обновляйте инкрементально: Используйте index_codebase для начальной индексации, затем reindex_changes для обновлений

2. Используйте фильтры: Сужайте область поиска с помощью fileTypes и pathPattern для получения лучших результатов

3. Осмысленные запросы: Используйте естественный язык, описывающий то, что вы ищете (например, "database connection pooling" вместо "db")

4. Сначала проверяйте статус: Используйте get_index_status, чтобы убедиться, что кодовая база проиндексирована перед поиском

5. Локальный эмбеддинг: Используйте Ollama (по умолчанию), чтобы все оставалось локальным и приватным

Производительность

Типичная производительность на современном ноутбуке (Apple M1/M2 или аналогичном):

Примечание: Время индексации зависит от провайдера эмбеддингов. Ollama (локально) — самый быстрый вариант для начальной индексации.

Поиск по истории Git

Индексируйте и ищите по истории коммитов git вашего репозитория, используя естественный язык. Идеально подходит для поиска прошлых исправлений, понимания паттернов изменений и обучения на предыдущем опыте.

Возможности

• Семантический поиск коммитов: Находите коммиты, описывая то, что вы ищете, на естественном языке

• Классификация Conventional Commits: Автоматическая классификация коммитов (feat, fix, refactor и т.д.)

• Инкрементальные обновления: Индексируйте только новые коммиты для эффективных обновлений

• Богатая фильтрация: Фильтрация по типу коммита, автору или диапазону дат

• Извлечение метаданных: Включает измененные файлы, вставки/удаления и полный контекст коммита

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

**1.