Qdrant MCP Server

A Model Context Protocol (MCP) server providing semantic search capabilities using Qdrant vector database with multiple embedding providers.

Features

• Zero Setup: Works out of the box with Ollama - no API keys required

• Privacy-First: Local embeddings and vector storage - data never leaves your machine

• Code Vectorization: Intelligent codebase indexing with AST-aware chunking and semantic code search

• Git History Search: Index commit history for semantic search over past changes, fixes, and patterns

• Advanced Search: Contextual search (code + git with correlations) and federated search across multiple repositories

• Multiple Providers: Ollama (default), OpenAI, Cohere, and Voyage AI

• Hybrid Search: Combine semantic and keyword search for better results

• Semantic Search: Natural language search with metadata filtering

• Incremental Indexing: Efficient updates - only re-index changed files

• Configurable Prompts: Create custom prompts for guided workflows without code changes

• Rate Limiting: Intelligent throttling with exponential backoff

• Full CRUD: Create, search, and manage collections and documents

• Structured Logging: JSON logging via Pino with configurable log levels

• Flexible Deployment: Run locally (stdio) or as a remote HTTP server

• API Key Authentication: Connect to secured Qdrant instances (Qdrant Cloud, self-hosted with API keys)

Quick Start

Prerequisites

• Node.js 22.x or 24.x

• Podman or Docker with Compose support

Installation

Configuration

Local Setup (stdio transport)

Or add to ~/.claude.json:

For Qdrant Cloud or secured instances, add --env QDRANT_API_KEY=your-key or set in env config.

Try it:

Enable example prompts: Copy prompts.example.json to prompts.json and restart. Use /prompt to list available prompts.

Remote Setup (HTTP transport)

⚠️ Security Warning: When deploying the HTTP transport in production:

• Always run behind a reverse proxy (nginx, Caddy) with HTTPS

• Implement authentication/authorization at the proxy level

• Use firewalls to restrict access to trusted networks

• Never expose directly to the public internet without protection

• Consider implementing rate limiting at the proxy level

• Monitor server logs for suspicious activity

Start the server:

Option 1: Using

Option 2: Add to

Using a different provider:

Restart after making changes.

See Advanced Configuration section below for all options.

Tools

Collection Management

Document Operations

Code Vectorization

Git History

Advanced Search

Resources

• qdrant://collections - List all collections

• qdrant://collection/{name} - Collection details

Configurable Prompts

Create custom prompts tailored to your specific use cases without modifying code. Prompts provide guided workflows for common tasks.

Note: By default, the server looks for prompts.json in the project root directory. If the file exists, prompts are automatically loaded. You can specify a custom path using the PROMPTS_CONFIG_FILE environment variable.

Setup

1. Create a prompts configuration file (e.g., prompts.json in the project root):

   See prompts.example.json for example configurations you can copy and customize.

2. Configure the server (optional - only needed for custom path):

If you place prompts.json in the project root, no additional configuration is needed. To use a custom path:

3. Use prompts in your AI assistant:

Claude Code:

VSCode:

Example Prompts

See prompts.example.json for ready-to-use prompts including:

• setup_rag_collection - Create RAG-optimized collections

• analyze_and_optimize - Collection insights and recommendations

• compare_search_strategies - Semantic vs hybrid search comparison

• migrate_to_hybrid - Collection migration guide

• debug_search_quality - Troubleshoot poor search results

• build_knowledge_base - Structured documentation with metadata

• index_git_history - Index repository commit history for semantic search

• search_project_history - Search git history to understand feature implementations

• investigate_code_with_history - Deep dive into code with contextual search

• cross_repo_search - Search patterns across multiple repositories

• trace_feature_evolution - Track how features evolved over time

• security_audit_search - Find security-related code and fixes

Template Syntax

Templates use {{variable}} placeholders:

• Required arguments must be provided

• Optional arguments use defaults if not specified

• Unknown variables are left as-is in the output

Code Vectorization

Intelligently index and search your codebase using semantic code search. Perfect for AI-assisted development, code exploration, and understanding large codebases.

Features

• AST-Aware Chunking: Intelligent code splitting at function/class boundaries using tree-sitter

• Multi-Language Support: 35+ file types including TypeScript, Python, Java, Go, Rust, C++, and more

• Incremental Updates: Only re-index changed files for fast updates

• Smart Ignore Patterns: Respects .gitignore, .dockerignore, and custom .contextignore files

• Semantic Search: Natural language queries to find relevant code

• Metadata Filtering: Filter by file type, path patterns, or language

• Local-First: All processing happens locally - your code never leaves your machine

Quick Start

1. Index your codebase:

2. Search your code:

3. Update after changes:

Usage Examples

Index a TypeScript Project

Search for Authentication Code

Search with Filters

Incremental Re-indexing

Check Indexing Status

Supported Languages

Programming Languages (35+ file types):

• 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

See configuration for full list and customization options.

Custom Ignore Patterns

Create a .contextignore file in your project root to specify additional patterns to ignore:

Best Practices

1. Index Once, Update Incrementally: Use index_codebase for initial indexing, then reindex_changes for updates

2. Use Filters: Narrow search scope with fileTypes and pathPattern for better results

3. Meaningful Queries: Use natural language that describes what you're looking for (e.g., "database connection pooling" instead of "db")

4. Check Status First: Use get_index_status to verify a codebase is indexed before searching

5. Local Embedding: Use Ollama (default) to keep everything local and private

Performance

Typical performance on a modern laptop (Apple M1/M2 or similar):

Note: Indexing time varies based on embedding provider. Ollama (local) is fastest for initial indexing.

Git History Search

Index and search your repository's git commit history using natural language. Perfect for finding past fixes, understanding change patterns, and learning from previous work.

Features

• Semantic Commit Search: Find commits by describing what you're looking for in natural language

• Conventional Commit Classification: Automatic classification of commits (feat, fix, refactor, etc.)

• Incremental Updates: Only index new commits for efficient updates

• Rich Filtering: Filter by commit type, author, or date range

• Metadata Extraction: Includes files changed, insertions/deletions, and full commit context

Quick Start

1. Index your repository's git history:

2. Search for relevant commits:

3. Keep index up to date:

Use Cases

• Finding Similar Fixes: "How was the null pointer issue in auth fixed before?"

• Understanding Patterns: "What refactoring was done to the database layer?"

• Learning from History: "Show me examples of API endpoint implementations"

• Code Archaeology: "What changes were made to the payment system last year?"

Advanced Search

Combine code and git history search for deeper codebase understanding. Requires repositories to be indexed with both index_codebase and index_git_history first.

• Contextual Search: Query code + git history together with automatic file-commit correlations

• Federated Search: Search across multiple repositories with RRF ranking

See Advanced Search Examples for detailed usage, workflows, and scenarios.

Examples

See examples/ directory for detailed guides:

• Basic Usage - Create collections, add documents, search

• Hybrid Search - Combine semantic and keyword search

• Knowledge Base - Structured documentation with metadata

• Advanced Filtering - Complex boolean filters

• Rate Limiting - Batch processing with cloud providers

• Code Search - Index codebases and semantic code search

• Advanced Search - Contextual and federated search across repositories

Advanced Configuration

Environment Variables

Core Configuration

Embedding Configuration

Code Vectorization Configuration

Git History Configuration

Provider Comparison

Note: Ollama models require pulling before use:

• Podman: podman exec ollama ollama pull <model-name>

• Docker: docker exec ollama ollama pull <model-name>

Troubleshooting

Development

Testing

748 tests across 27 test files with 97%+ coverage:

• Unit Tests: QdrantManager (56), Ollama (41), OpenAI (25), Cohere (29), Voyage (31), Factory (43), Prompts (50), Transport (15), MCP Server (19)

• Integration Tests: Code indexer (56), scanner (15), chunker (24), synchronizer (42), snapshot (26), merkle tree (28)

• Git History Tests: Git extractor (28), extractor integration (11), chunker (30), indexer (42), synchronizer (18)

• Advanced Search Tests: Federated tools (30) - normalizeScores, calculateRRFScore, buildCorrelations, contextual_search, federated_search

CI/CD: GitHub Actions runs build, type-check, and tests on Node.js 22.x and 24.x for every push/PR.

Contributing

Contributions welcome! See CONTRIBUTING.md for:

• Development workflow

• Conventional commit format (feat:, fix:, BREAKING CHANGE:)

• Testing requirements (run npm test, npm run type-check, npm run build)

Automated releases: Semantic versioning via conventional commits - feat: → minor, fix: → patch, BREAKING CHANGE: → major.

Acknowledgments

The code vectorization feature is inspired by and builds upon concepts from the excellent claude-context project (MIT License, Copyright 2025 Zilliz).

License

MIT - see LICENSE file.