W3 Mcp Server Qdrant

W3 MCP Qdrant Server

Python MCP server for vector search using Qdrant vector database and Ollama embeddings.

Status: ✅ Working with Qdrant vector search and Ollama embeddings + Advanced query techniques

Features

• qdrant_search - Search for similar documents using text queries (auto-embedded via Ollama)
• ✨ Query Expansion - Generate N query variations, search all, merge with RRF
• ✨ HyDE - Hypothetical Document Embeddings for semantic enrichment
• ✨ Reranking - Use LLM to reorder results by relevance
• qdrantlistcollections - List and manage Qdrant collections

Supports flexible output formats (Markdown or JSON) with configurable similarity thresholds and advanced search options.

Quick Start

1. Prerequisites Setup

Qdrant Server

# Using Docker (Recommended)
docker run -p 6333:6333 qdrant/qdrant:latest

Or install locally: Qdrant Quick Start

Ollama Server

# Install: https://ollama.ai
ollama pull bge-m3
ollama pull mistral
ollama serve

Available embedding models:

• bge-m3 (384 dims) - ⭐ recommended - best quality-speed balance
• nomic-embed-text (768 dims) - balanced, good for general use
• mxbai-embed-large (1024 dims) - highest quality
• all-minilm (384 dims) - ultra-lightweight, good for mobile

2. Clean Setup (Important!)

cd /path/to/w3-mcp-server-qdrant

# Remove old lockfile and venv
rm -rf uv.lock .venv venv

# Unset old environment variable
unset VIRTUAL_ENV

3. Install Dependencies with uv

# Install all Python dependencies using uv
uv sync

That's it! uv sync installs all dependencies including MCP, pydantic, qdrant-client, and httpx.

4. Configure Environment

Create a .env file from template:

cp .env.example .env

Edit .env:

# Qdrant Configuration
QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=  # Optional if using API key auth

# Ollama Configuration
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_EMBED_MODEL=bge-m3:latest
OLLAMA_RERANK_MODEL=mistral  # For query expansion and reranking

Or export environment variables:

export QDRANT_URL=http://localhost:6333
export OLLAMA_BASE_URL=http://localhost:11434
export OLLAMA_EMBED_MODEL=bge-m3:latest
export OLLAMA_RERANK_MODEL=mistral

5. Verify Installation

# Check Qdrant
curl http://localhost:6333/health

# Check Ollama
curl http://localhost:11434/api/tags

# Check Python env
uv run python -c "from mcp.server.fastmcp import FastMCP; print('✓ MCP ready')"

6. Test with MCP Inspector

# Start MCP Inspector (interactive web UI)
uv run mcp dev server.py

Opens URL like:

http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=...

Features:

• ✅ Available tools listed in sidebar
• ✅ Test each tool interactively with JSON input
• ✅ Real-time request/response viewing
• ✅ Server logs and debugging
• ✅ No extra dependencies needed

Usage

Option A: MCP Inspector (Development)

Best way to test and debug:

cd /path/to/w3-mcp-server-qdrant

# Start inspector
uv run mcp dev server.py

Opens web UI at http://localhost:5173:

• See available tools
• Test each tool with JSON input
• View request/response in real-time
• See server logs

Option B: Direct Python

# Run server (stdio mode)
uv run python server.py

Option C: Claude Code Integration

Method 1: Local Source (Development)

Edit ~/.claude/claude_config.json:

{
  "mcpServers": {
    "qdrant": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "server.py"],
      "cwd": "/path/to/w3-mcp-server-qdrant",
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "OLLAMA_BASE_URL": "http://localhost:11434",
        "OLLAMA_EMBED_MODEL": "bge-m3:latest",
        "OLLAMA_RERANK_MODEL": "mistral"
      }
    }
  }
}

Advantages:

• ✅ Run latest development version
• ✅ Easy to modify and test changes
• ✅ Direct access to source code

Method 2: PyPI Installation (When Published)

Install from PyPI (always fetch latest version):

uv run --with w3-mcp-server-qdrant --refresh w3-mcp-server-qdrant

Edit ~/.claude/claude_config.json:

{
  "mcpServers": {
    "qdrant": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--with", "w3-mcp-server-qdrant", "--refresh", "w3-mcp-server-qdrant"],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "OLLAMA_BASE_URL": "http://localhost:11434",
        "OLLAMA_EMBED_MODEL": "bge-m3:latest",
        "OLLAMA_RERANK_MODEL": "mistral"
      }
    }
  }
}

Advantages:

• ✅ No need to clone repository
• ✅ Easy version management
• ✅ Automatic dependency isolation

Then restart Claude Code.

Tools Documentation

qdrant_search

Search for similar documents in a collection using text query (auto-embedded via Ollama).

Supports advanced search techniques: query expansion, hypothetical document embeddings (HyDE), and LLM-based reranking.

Basic Parameters

| Parameter | Type | Default | Description | | --- | --- | --- | --- | | collection_name | string | required | Name of the collection to search | | query_text | string | required | Text to search for (auto-embedded via Ollama) | | limit | integer | 5 | Max results to return (1-100) | | score_threshold | float | 0.0 | Minimum similarity threshold (0.0-1.0) | | fields | string | "" | Comma-separated metadata fields to return (empty = all) | | response_format | string | "markdown" | "markdown" or "json" |

Advanced Parameters - Query Expansion

Generate N query variations, search all in parallel, merge results with Reciprocal Rank Fusion:

| Parameter | Type | Default | Description | | --- | --- | --- | --- | | expand_query | boolean | false | Enable query expansion | | expand_query_count | integer | 3 | Number of variations to generate (1-10) |

Advanced Parameters - HyDE

Generate a hypothetical document matching the query intent, then embed it:

| Parameter | Type | Default | Description | | --- | --- | --- | --- | | use_hyde | boolean | false | Enable HyDE | | hyde_combine_original | boolean | true | Also search original query + HyDE doc |

Advanced Parameters - Reranking

Use LLM to reorder results by relevance to the original query:

| Parameter | Type | Default | Description | | --- | --- | --- | --- | | rerank | boolean | false | Enable LLM reranking | | rerank_top_n | integer | 10 | Number of results to rerank (1-100) |

Examples

Example 1: Basic search

{
  "collection_name": "docs",
  "query_text": "machine learning",
  "limit": 5
}

Example 2: Query expansion (good recall)

{
  "collection_name": "docs",
  "query_text": "machine learning",
  "expand_query": true,
  "expand_query_count": 5,
  "limit": 5
}

Example 3: HyDE (semantic understanding)

{
  "collection_name": "docs",
  "query_text": "machine learning",
  "use_hyde": true,
  "hyde_combine_original": true,
  "limit": 5
}

Example 4: Full combo (best quality, slower)

{
  "collection_name": "docs",
  "query_text": "machine learning",
  "expand_query": true,
  "expand_query_count": 3,
  "use_hyde": true,
  "rerank": true,
  "rerank_top_n": 15,
  "limit": 5
}

Output Format

Returns JSON with search metadata and ranked results:

{
  "query": "machine learning",
  "collection": "docs",
  "total": 3,
  "search_method": "rrf+hyde+expand+rerank",
  "results": [
    {
      "index": 1,
      "id": "doc_123",
      "score": 0.0273,
      "metadata": {
        "title": "Machine Learning Basics",
        "author": "Jane Doe"
      }
    }
  ]
}

Note: search_method field indicates which techniques were applied:

• basic - simple vector search
• rrf - multiple searches merged with Reciprocal Rank Fusion
• rrf+hyde - RRF with HyDE
• rrf+expand - RRF with query expansion
• rrf+hyde+expand+rerank - all techniques combined

---

qdrantlistcollections

List all collections in Qdrant with metadata.

Parameters:

• response_format (string): "markdown" or "json" (default: "markdown")

Example:

{
  "response_format": "json"
}

Output:

{
  "collections": [
    {
      "name": "tech_docs",
      "points_count": 1250,
      "vector_size": 768
    },
    {
      "name": "papers",
      "points_count": 3840,
      "vector_size": 1024
    }
  ]
}

Configuration

QDRANT_URL

Specifies the URL of your Qdrant server.

Set via:

1. Environment variable:

``bash export QDRANT_URL=http://localhost:6333 uv run python server.py ``

1. .env file:

``bash QDRANT_URL=http://localhost:6333 ``

1. In claude_config.json:

``json "env": { "QDRANT_URL": "http://localhost:6333" } ``

OLLAMABASEURL

Specifies the URL of your Ollama server.

Default: http://localhost:11434

OLLAMAEMBEDMODEL

Specifies which embedding model to use for embedding search queries and documents.

Default: bge-m3:latest

Recommended embedding models:

• bge-m3 (384 dims) - ⭐ Recommended - best quality-to-speed ratio
• nomic-embed-text (768 dims) - balanced, good for most use cases
• all-minilm (384 dims) - fast, lightweight
• mxbai-embed-large (1024 dims) - highest quality but slower

OLLAMARERANKMODEL

Specifies which LLM model to use for advanced features (query expansion, HyDE, reranking).

Default: mistral

Recommended models:

• mistral (7B) - ⭐ Recommended - good quality, reasonable speed
• qwen2.5-coder (7B) - high quality but optimized for code
• llama3.2 (3B) - smaller, faster but lower quality
• neural-chat (7B) - good for instruction-following

Note: Only used when expand_query=true, use_hyde=true, or rerank=true

Project Structure

w3-mcp-server-qdrant/
├── server.py              # MCP server entry point
├── pyproject.toml         # Project config
├── .env.example           # Environment variables template
├── README.md              # This file
└── tests/
    └── test_mcp_server.py # Integration tests

How It Works

Architecture

MCP Client (Claude, IDE, etc.)
    ↓
MCP Server (server.py)
    ├── Ollama: text → embedding vector
    └── Qdrant: vector search

Search Flow

1. User provides text query
2. Ollama embeds query → embedding vector
3. Qdrant searches for similar vectors
4. Results returned with scores and metadata

Examples

Search documents

# Via Claude/MCP interface
qdrant_search(
    collection_name="tech_docs",
    query_text="machine learning algorithms",
    limit=5,
    score_threshold=0.6,
    response_format="markdown"
)

List collections

# Via Claude/MCP interface
qdrant_list_collections(response_format="json")

Development

Run tests using uv

uv run pytest tests/

Code formatting with uv

uv run black server.py
uv run ruff check server.py

Testing with MCP Inspector

uv run mcp dev server.py

Web UI at http://localhost:5173 shows:

• Available tools and schemas
• Real-time request/response
• Server logs
• Interactive testing

Performance Tips

Basic Search Optimization

• Score threshold: Use score_threshold to filter low-relevance results and reduce noise
• Result limit: Adjust limit parameter (1-100) to balance quality vs. speed
• Embedding model: Choose based on quality vs. speed tradeoff:
• nomic-embed-text: balanced (recommended)
• all-minilm: fast, lightweight
• mxbai-embed-large: higher quality but slower

Advanced Features Trade-offs

| Feature | Quality | Speed | Use Case | | --- | --- | --- | --- | | Basic search | ⭐⭐ | ⚡⚡⚡ | Clear, specific queries | | Query expansion | ⭐⭐⭐ | ⚡⚡ | Ambiguous queries, high recall needed | | HyDE | ⭐⭐⭐ | ⚡⚡ | Semantic understanding important | | Reranking | ⭐⭐⭐⭐ | ⚡ | Precision critical, can wait 1-2s | | All combined | ⭐⭐⭐⭐⭐ | ⚡ | Best quality, time not critical |

Performance Strategy

• Fast path: Basic search with limit=5
• Balanced: expand_query=true, expand_query_count=3
• High quality: Add use_hyde=true
• Maximum quality: Add rerank=true (slowest, ~5-10s)

Troubleshooting

Qdrant connection error

# Check if Qdrant is running
curl http://localhost:6333/health

# Start Qdrant with Docker
docker run -p 6333:6333 qdrant/qdrant:latest

Ollama embedding failed

# Check if Ollama is running
curl http://localhost:11434/api/tags

# Pull embedding model
ollama pull nomic-embed-text

# Start Ollama
ollama serve

Collection not found

• Ensure collection exists in Qdrant
• Create collection through Qdrant UI or external tools
• Verify collection name matches exactly

MCP module not found

# Install dependencies with uv
uv sync

Server hangs on startup

• Check if Qdrant server is running and accessible
• Check if Ollama server is running
• Try: curl http://localhost:6333/health and curl http://localhost:11434/api/tags

Implemented Features

• [x] Query expansion with LLM-generated variations
• [x] HyDE (Hypothetical Document Embeddings)
• [x] Reciprocal Rank Fusion (RRF) for result merging
• [x] LLM-based result reranking
• [x] Parallel async embedding and search

Future Enhancements

• [ ] Support for additional embedding models
• [ ] Batch vector operations
• [ ] Collection creation/deletion tools
• [ ] Vector update and delete operations
• [ ] Semantic search filters
• [ ] Caching for query expansions
• [ ] Custom RRF weights configuration

References

• Qdrant Documentation
• Ollama
• Model Context Protocol
• FastMCP

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: famtong8-dev
• Source: famtong8-dev/w3-mcp-server-qdrant
• License: MIT
• Homepage: https://pypi.org/project/w3-mcp-server-qdrant/

Install and usage instructions live in the source repository linked above.