Qdrant MCP Server

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

- 🔍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

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

# 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

Create a.envfile 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/

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

# 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

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"

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}")

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

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())

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" )

# 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

# Only index changed files since last run qdrant-indexer /path/to/code --incremental # Force reindex of all files qdrant-indexer /path/to/code --force

# 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

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

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

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

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

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

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

# Enable verbose logging qdrant-mcp --debug # Test connectivity qdrant-mcp --test-connection # Validate configuration qdrant-mcp --validate-config

We welcome contributions! Please seeCONTRIBUTING.mdfor guidelines.

# 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/

- Built for theModel Context Protocol
- Powered byQdrantvector database
- Embeddings byOpenAI
- Originally developed forKinDash

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

A server for document management and semantic search using AI embeddings, with local JSON storage.