qdrant-loader-mcp-server 1.0.0

A Model Context Protocol (MCP) server that provides RAG capabilities to Cursor using Qdrant.

QDrant Loader MCP Server

A Model Context Protocol (MCP) server that brings advanced RAG search to AI development tools. Part of the QDrant Loader monorepo ecosystem.

🎯 What It Does

• Intelligent search via semantic, hierarchy-aware, and attachment-focused tools
• Seamless integration with Cursor, Windsurf, Claude Desktop, and any MCP-compatible tool
• Context understanding — document hierarchies, file relationships, and rich metadata
• Streaming responses for fast, real-time search results

🔌 Supported AI Tools

Tool	Status	Integration Features
Cursor	✅ Full Support	Context-aware code assistance, documentation lookup, intelligent suggestions
Windsurf	✅ Compatible	MCP protocol integration, semantic search capabilities
Claude Desktop	✅ Compatible	Direct MCP integration, conversational search interface
Other MCP Tools	✅ Compatible	Any tool supporting MCP 2024-11-05 specification

For per-tool JSON configuration, see MCP setup and integration.

🔍 Search Tools

Core search tools

Tool	Purpose
search	General semantic search across all content
hierarchy_search	Confluence-aware search with parent/child page relationships
attachment_search	File-focused search with parent document context

Cross-document intelligence

analyze_relationships, find_similar_documents, detect_document_conflicts, find_complementary_content, cluster_documents, expand_document, expand_cluster, expand_chunk_context

For full parameter references and usage examples, see MCP search capabilities.

📦 Installation

pip install qdrant-loader-mcp-server

For the full ingestion + MCP pipeline:

pip install qdrant-loader qdrant-loader-mcp-server

🚀 Quick Start

1. Set environment variables

export QDRANT_URL="http://localhost:6333"
export QDRANT_API_KEY="your_api_key"        # Required for QDrant Cloud
export LLM_API_KEY="your_openai_key"
export MCP_DISABLE_CONSOLE_LOGGING="true"   # Required for Cursor

2. Start the server

mcp-qdrant-loader

# With debug logging
mcp-qdrant-loader --log-level DEBUG

# Help
mcp-qdrant-loader --help

3. Test the connection

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search","arguments":{"query":"test","limit":1}}}' | mcp-qdrant-loader

🔧 Configuration

Environment variables

Variable	Description	Default	Required
QDRANT_URL	QDrant instance URL	http://localhost:6333	Yes
QDRANT_API_KEY	QDrant API key	None	Cloud only
QDRANT_COLLECTION_NAME	Collection name	documents	No
LLM_API_KEY	LLM API key for embeddings	None	Yes
MCP_LOG_LEVEL	Logging level	INFO	No
MCP_LOG_FILE	Log file path	None	No
MCP_DISABLE_CONSOLE_LOGGING	Disable console output	false	Yes for Cursor
SEARCH_MAX_CONCURRENT	Max concurrent Qdrant queries per worker	4	No

For Cursor: Always set MCP_DISABLE_CONSOLE_LOGGING=true to prevent JSON-RPC interference. Use MCP_LOG_FILE to capture logs instead.

HTTP transport and workers

For production deployments with multiple worker processes:

# HTTP transport — eliminates GIL contention for CPU-bound work
mcp-qdrant-loader --transport http --port 8080 --workers 4

Each worker has its own event loop and Qdrant connection pool. Total concurrent Qdrant load = workers × SEARCH_MAX_CONCURRENT.

Workers	SEARCH_MAX_CONCURRENT	Max concurrent Qdrant queries
1	4 (default)	4
4	4 (default)	16
4	2	8

If you see 408 Request Timeout from Qdrant, lower SEARCH_MAX_CONCURRENT:

export SEARCH_MAX_CONCURRENT=2
mcp-qdrant-loader --transport http --workers 4

🎯 Usage Examples

Ask your AI assistant in natural language:

• "Find documentation about authentication in our API"
• "Show me examples of error handling patterns in our codebase"
• "Find all PDF attachments related to database schema"
• "Show me the hierarchy of pages under the Architecture section"

🏗️ Architecture

MCP Protocol Implementation

• Full MCP 2024-11-05 compliance with proper JSON-RPC communication
• Tool registration for search, hierarchy_search, and attachment_search
• Streaming responses for large result sets
• Error handling with proper MCP error codes

Search Engine Components

• Embedding Service — Generates query embeddings using the configured LLM provider
• Vector Search — Performs semantic similarity search in QDrant
• Metadata Processor — Enriches results with hierarchy and attachment information
• Result Formatter — Creates rich, contextual response formatting
• Caching Layer — Optimizes performance for repeated queries

Data Flow

AI Tool → MCP Server → QDrant Search → Result Processing → Formatted Response
    ↓         ↓            ↓              ↓                ↓
Cursor    JSON-RPC    Vector Query   Metadata         Rich Context
Windsurf  Protocol    Embedding      Enrichment       Visual Indicators
Claude    Tool Call   Similarity     Hierarchy        Relationship Info
Other     Streaming   Ranking        Attachments      Source Attribution

For system-level architecture, see Architecture guide.

📚 Canonical Documentation

• Monorepo overview - Repository layout, package responsibilities, and navigation entry points.
• MCP server guide - End-to-end overview of MCP usage with QDrant Loader.
• MCP setup and integration - Tool-specific setup steps and integration configuration.
• MCP search capabilities - Available search tools, parameters, and usage patterns.
• Environment variables reference - Required and optional runtime variables for server behavior.

🤝 Contributing

See CONTRIBUTING - Contribution guidelines, development standards, and pull request process.