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

• 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

• 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+

• Podman or Docker with Compose support

Installation

Configuration

Local Setup (stdio transport)

Add to ~/.claude/claude_code_config.json:

Connecting to Secured Qdrant Instances

For Qdrant Cloud or self-hosted instances with API key authentication:

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:

Configure client:

Using a different provider:

Restart after making changes.

See Advanced Configuration section below for all options.

Tools

Collection Management

Document Operations

Code Vectorization

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:

• find_similar_docs - Semantic search with result explanation

• setup_rag_collection - Create RAG-optimized collections

• analyze_collection - Collection insights and recommendations

• bulk_add_documents - Guided bulk document insertion

• search_with_filter - Metadata filtering assistance

• compare_search_methods - Semantic vs hybrid search comparison

• collection_maintenance - Maintenance and cleanup workflows

• migrate_to_hybrid - Collection migration guide

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.

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 Configuration

Environment Variables

Core Configuration

Embedding Configuration

Code Vectorization 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

586 tests across 21 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)

CI/CD: GitHub Actions runs build, type-check, and tests on Node.js 22 LTS 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.