Qdrant MCP Server

A Model Context Protocol (MCP) server that provides semantic code search capabilities using Qdrant vector database and OpenAI embeddings.

Features

🔍 Semantic Code Search - Find code by meaning, not just keywords
🚀 Fast Indexing - Efficient incremental indexing of large codebases
🤖 MCP Integration - Works seamlessly with Claude and other MCP clients
📊 Background Monitoring - Automatic reindexing of changed files
🎯 Smart Filtering - Respects .gitignore and custom patterns
💾 Persistent Storage - Embeddings stored in Qdrant for fast retrieval

Installation

Prerequisites

Node.js 18+
Python 3.8+
Docker (for Qdrant) or Qdrant Cloud account
OpenAI API key

Quick Start

# Install the package
npm install -g @kindash/qdrant-mcp-server

# Or with pip
pip install qdrant-mcp-server

# Set up environment variables
export OPENAI_API_KEY="your-api-key"
export QDRANT_URL="http://localhost:6333"  # or your Qdrant Cloud URL
export QDRANT_API_KEY="your-qdrant-api-key"  # if using Qdrant Cloud

# Start Qdrant (if using Docker)
docker run -p 6333:6333 qdrant/qdrant

# Index your codebase
qdrant-indexer /path/to/your/code

# Start the MCP server
qdrant-mcp

Configuration

Environment Variables

Create a .env file in your project root:

# Required
OPENAI_API_KEY=sk-...

# Qdrant Configuration
QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=  # Optional, for Qdrant Cloud
QDRANT_COLLECTION_NAME=codebase  # Default: codebase

# Indexing Configuration
MAX_FILE_SIZE=1048576  # Maximum file size to index (default: 1MB)
BATCH_SIZE=10  # Number of files to process in parallel
EMBEDDING_MODEL=text-embedding-3-small  # OpenAI embedding model

# File Patterns
INCLUDE_PATTERNS=**/*.{js,ts,jsx,tsx,py,java,go,rs,cpp,c,h}
EXCLUDE_PATTERNS=**/node_modules/**,**/.git/**,**/dist/**

MCP Configuration

Add to your Claude Desktop config (~/.claude/config.json):

{
  "mcpServers": {
    "qdrant-search": {
      "command": "qdrant-mcp",
      "args": ["--collection", "my-codebase"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "QDRANT_URL": "http://localhost:6333"
      }
    }
  }
}

Usage

Command Line Interface

# Index entire codebase
qdrant-indexer /path/to/code

# Index with custom patterns
qdrant-indexer /path/to/code --include "*.py" --exclude "tests/*"

# Index specific files
qdrant-indexer file1.js file2.py file3.ts

# Start background indexer
qdrant-control start

# Check indexer status
qdrant-control status

# Stop background indexer
qdrant-control stop

In Claude

Once configured, you can use natural language queries:

"Find all authentication code"
"Show me files that handle user permissions"
"What code is similar to the PaymentService class?"
"Find all API endpoints related to users"
"Show me error handling patterns in the codebase"

Programmatic Usage

from qdrant_mcp_server import QdrantIndexer, QdrantSearcher

# Initialize indexer
indexer = QdrantIndexer(
    openai_api_key="sk-...",
    qdrant_url="http://localhost:6333",
    collection_name="my-codebase"
)

# Index files
indexer.index_directory("/path/to/code")

# Search
searcher = QdrantSearcher(
    qdrant_url="http://localhost:6333",
    collection_name="my-codebase"
)

results = searcher.search("authentication logic", limit=10)
for result in results:
    print(f"{result.file_path}: {result.score}")

Architecture

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Claude/MCP    │────▶│  MCP Server      │────▶│     Qdrant      │
│     Client      │     │  (Python)        │     │   Vector DB     │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                               │                           ▲
                               ▼                           │
                        ┌──────────────────┐              │
                        │  OpenAI API      │              │
                        │  (Embeddings)    │──────────────┘
                        └──────────────────┘

Advanced Configuration

Custom File Processors

from qdrant_mcp_server import FileProcessor

class MyCustomProcessor(FileProcessor):
    def process(self, file_path: str, content: str) -> dict:
        # Custom processing logic
        return {
            "content": processed_content,
            "metadata": custom_metadata
        }

# Register processor
indexer.register_processor(".myext", MyCustomProcessor())

Embedding Models

Support for multiple embedding providers:

# OpenAI (default)
indexer = QdrantIndexer(embedding_provider="openai")

# Cohere
indexer = QdrantIndexer(
    embedding_provider="cohere",
    cohere_api_key="..."
)

# Local models (upcoming)
indexer = QdrantIndexer(
    embedding_provider="local",
    model_path="/path/to/model"
)

Performance Optimization

Batch Processing

# Process files in larger batches (reduces API calls)
qdrant-indexer /path/to/code --batch-size 50

# Limit concurrent requests
qdrant-indexer /path/to/code --max-concurrent 5

Incremental Indexing

# Only index changed files since last run
qdrant-indexer /path/to/code --incremental

# Force reindex of all files
qdrant-indexer /path/to/code --force

Cost Estimation

# Estimate indexing costs before running
qdrant-indexer /path/to/code --dry-run

# Output:
# Files to index: 1,234
# Estimated tokens: 2,456,789
# Estimated cost: $0.43

Monitoring

Web UI (Coming Soon)

# Start monitoring dashboard
qdrant-mcp --web-ui --port 8080

Logs

# View indexer logs
tail -f ~/.qdrant-mcp/logs/indexer.log

# View search queries
tail -f ~/.qdrant-mcp/logs/queries.log

Metrics

Files indexed
Tokens processed
Search queries per minute
Average response time
Cache hit rate

Troubleshooting

Common Issues

"Connection refused" error

Ensure Qdrant is running: docker ps
Check QDRANT_URL is correct
Verify firewall settings

"Rate limit exceeded" error

Reduce batch size: --batch-size 5
Add delay between requests: --delay 1000
Use a different OpenAI tier

"Out of memory" error

Process fewer files at once
Increase Node.js memory: NODE_OPTIONS="--max-old-space-size=4096"
Use streaming mode for large files

Debug Mode

# Enable verbose logging
qdrant-mcp --debug

# Test connectivity
qdrant-mcp --test-connection

# Validate configuration
qdrant-mcp --validate-config

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

# Clone the repository
git clone https://github.com/kindash/qdrant-mcp-server
cd qdrant-mcp-server

# Install dependencies
npm install
pip install -e .

# Run tests
npm test
pytest

# Run linting
npm run lint
flake8 src/

License

MIT License - see LICENSE for details.

Acknowledgments

Built for the Model Context Protocol
Powered by Qdrant vector database
Embeddings by OpenAI
Originally developed for KinDash

Support

📧 Email: support@kindash.app
💬 Discord: Join our community
🐛 Issues: GitHub Issues
📖 Docs: Full Documentation