qdrant-mcp-ollama

A Model Context Protocol (MCP) server for Qdrant vector database that uses Ollama for GPU-accelerated embeddings.

Why not the official mcp-server-qdrant?

The official Qdrant MCP server uses FastEmbed for embeddings, which:

• Runs on CPU only — slow on large codebases, underutilizes modern GPUs
• Uses a small model (all-MiniLM-L6-v2, 384-dim) — lower quality embeddings
• Single-process lock in local mode — only one MCP client can access the database at a time

This server solves all three problems:

	Official mcp-server-qdrant	qdrant-mcp-ollama
Embedding engine	FastEmbed (CPU)	Ollama (GPU)
Default model	all-MiniLM-L6-v2 (384-dim, 80MB)	bge-m3 (1024-dim, 1.2GB)
Concurrent access	No (local mode)	Yes (Qdrant server)
Model flexibility	FastEmbed models only	Any Ollama embedding model

Architecture

┌──────────────┐     ┌────────────────────┐     ┌─────────────┐
│  MCP Client   │────>│  qdrant-mcp-ollama │────>│   Ollama    │
│ (Claude Code, │     │    (server.py)      │     │  (GPU)      │
│  Kilo Code,   │<────│                    │     └─────────────┘
│  Cursor, etc) │     └────────┬───────────┘
└──────────────┘              │
                              v
                   ┌────────────────────┐
                   │   Qdrant Server    │
                   │  (Docker, :6333)   │
                   │  Storage: local    │
                   │  disk / cloud      │
                   └────────────────────┘

Prerequisites

• Ollama — installed and running with an embedding model pulled
• Docker — for running the Qdrant server
• uv — Python package manager (recommended) or pip

Quick Start

1. Pull an embedding model in Ollama

ollama pull bge-m3

2. Start the Qdrant server

docker run -d --name qdrant-server \
  -p 6333:6333 -p 6334:6334 \
  -v qdrant-storage:/qdrant/storage \
  --restart unless-stopped \
  qdrant/qdrant:latest

3. Run the MCP server

# No install needed — uv downloads dependencies on-the-fly:
QDRANT_URL="http://localhost:6333" \
EMBEDDING_MODEL="bge-m3" \
uv run --with fastmcp --with qdrant-client --with httpx python server.py

4. Embed a codebase

uv run --with qdrant-client --with httpx python embed_codebase.py \
  /path/to/your/project my-project --preset python

5. Search from your MCP client

Once configured (see sections below), ask your AI assistant:

"Search the codebase for authentication logic"

It will use the qdrant_find tool to return semantically relevant code chunks.

---

Setting Up the Qdrant Server

Option A: Docker (recommended)

Store data on a specific drive (e.g., E: on Windows):

# Create storage directories
mkdir -p E:/qdrant-storage E:/qdrant-snapshots

# Start Qdrant with persistent storage
docker run -d --name qdrant-server \
  -p 6333:6333 -p 6334:6334 \
  -v E:/qdrant-storage:/qdrant/storage \
  -v E:/qdrant-snapshots:/qdrant/snapshots \
  --restart unless-stopped \
  qdrant/qdrant:latest

On Linux/macOS:

docker run -d --name qdrant-server \
  -p 6333:6333 -p 6334:6334 \
  -v ~/qdrant-storage:/qdrant/storage \
  --restart unless-stopped \
  qdrant/qdrant:latest

The --restart unless-stopped flag ensures Qdrant starts automatically with Docker Desktop.

Verify it's running:

docker ps --filter name=qdrant-server
# Or open http://localhost:6333/dashboard in your browser

Option B: Qdrant Cloud

Sign up at cloud.qdrant.io and get your URL and API key. Then set:

QDRANT_URL="https://your-cluster.cloud.qdrant.io:6333"
QDRANT_API_KEY="your-api-key"

Note: The QDRANT_API_KEY environment variable is passed through to the Qdrant client automatically.

---

Embedding a Codebase

The embed_codebase.py script scans a directory, chunks source files, and bulk-embeds them into Qdrant using Ollama on GPU.

Basic usage

uv run --with qdrant-client --with httpx python embed_codebase.py <directory> <collection-name>

Using extension presets

# Python project
python embed_codebase.py ./my-api api-backend --preset python

# Full-stack web project
python embed_codebase.py ./my-app frontend --preset web

# R / bioinformatics project
python embed_codebase.py ./analysis bio-analysis --preset r

# Everything
python embed_codebase.py ./mono-repo all-code --preset all

Custom extensions

python embed_codebase.py ./project my-collection --extensions .py .sql .sh .yaml

Available presets

Preset	Extensions
python	.py .pyi
javascript	.js .jsx .mjs .cjs
typescript	.ts .tsx
web	.js .jsx .ts .tsx .vue .svelte .html .css .scss
r	.R .r .Rmd .rmd
java	.java
csharp	.cs
go	.go
rust	.rs
cpp	.cpp .hpp .cc .hh .c .h
all	All common source extensions

If no --preset or --extensions is provided, the script auto-detects file types.

All options

usage: embed_codebase.py <directory> <collection> [options]

positional arguments:
  directory              Path to the codebase directory
  collection             Qdrant collection name

options:
  --extensions EXT [EXT ...]  File extensions to include (e.g. .py .ts)
  --preset PRESET             Use a preset group of extensions
  --model MODEL               Ollama embedding model (default: bge-m3)
  --qdrant-url URL            Qdrant server URL (default: http://localhost:6333)
  --ollama-url URL            Ollama server URL (default: http://localhost:11434)
  --chunk-size N              Max lines per chunk (default: 80)
  --chunk-overlap N           Overlap lines between chunks (default: 10)
  --batch-size N              Upload batch size for Qdrant (default: 500)
  --append                    Append to existing collection instead of replacing

Append mode

By default, re-running the script replaces the collection. Use --append to add to an existing collection:

# First embed
python embed_codebase.py ./src main-code --preset typescript

# Add more files later
python embed_codebase.py ./docs main-code --extensions .md --append

---

Multi-Codebase Usage

Use separate collections for each codebase to keep search results scoped and relevant:

# Project A
python embed_codebase.py ~/projects/api-server api-server --preset python

# Project B
python embed_codebase.py ~/projects/web-app web-app --preset web

# Project C
python embed_codebase.py ~/projects/data-pipeline data-pipeline --preset python

When configuring the MCP server:

• Without COLLECTION_NAME: You must specify the collection per query. This is ideal when one MCP server serves multiple projects.
• With COLLECTION_NAME: A default collection is used automatically. Set this per-project if your MCP client supports project-scoped configuration.

---

Configuring Claude Code

Add the MCP server

claude mcp add qdrant -s user \
  -e QDRANT_URL="http://localhost:6333" \
  -e OLLAMA_URL="http://localhost:11434" \
  -e EMBEDDING_MODEL="bge-m3" \
  -- uv run --with fastmcp --with qdrant-client --with httpx \
     python /path/to/qdrant-mcp-ollama/server.py

Replace /path/to/qdrant-mcp-ollama/ with the actual path where you cloned this repo.

With a default collection

If you primarily work on one project:

claude mcp add qdrant -s user \
  -e QDRANT_URL="http://localhost:6333" \
  -e OLLAMA_URL="http://localhost:11434" \
  -e EMBEDDING_MODEL="bge-m3" \
  -e COLLECTION_NAME="my-project" \
  -- uv run --with fastmcp --with qdrant-client --with httpx \
     python /path/to/qdrant-mcp-ollama/server.py

Verify

claude mcp list
# Should show: qdrant: ... ✓ Connected

claude mcp get qdrant
# Shows full configuration details

Usage in Claude Code

Once configured, Claude Code can use these tools:

• qdrant_store — Store information: "Store this authentication pattern in Qdrant"
• qdrant_find — Search: "Find code related to database migrations"

For multi-collection setups (no default), specify the collection:

"Search the api-server collection for rate limiting logic"

---

Configuring Kilo Code (VS Code Extension)

Kilo Code is a VS Code extension with built-in MCP support.

Option 1: Manual MCP configuration

1. Open Kilo Code settings in VS Code
2. Navigate to MCP Servers configuration
3. Add a new server with:

Field	Value
Name	qdrant
Command	uv
Arguments	run --with fastmcp --with qdrant-client --with httpx python /path/to/server.py

4. Set environment variables:

Variable	Value
QDRANT_URL	http://localhost:6333
OLLAMA_URL	http://localhost:11434
EMBEDDING_MODEL	bge-m3
COLLECTION_NAME	Your project collection name (e.g., my-project)

Option 2: VS Code settings.json

Add to your VS Code settings.json (Ctrl+Shift+P > Preferences: Open User Settings (JSON)):

{
  "kilocode.mcpServers": {
    "qdrant": {
      "command": "uv",
      "args": [
        "run", "--with", "fastmcp", "--with", "qdrant-client", "--with", "httpx",
        "python", "/path/to/qdrant-mcp-ollama/server.py"
      ],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "OLLAMA_URL": "http://localhost:11434",
        "EMBEDDING_MODEL": "bge-m3",
        "COLLECTION_NAME": "my-project"
      }
    }
  }
}

Per-project setup in Kilo Code

For multi-codebase setups, configure Kilo Code at project scope (not global) with a project-specific COLLECTION_NAME. This way each workspace searches only its own codebase.

---

Configuring Other MCP Clients

Cursor / Windsurf

Run the server with SSE transport for remote-capable clients:

QDRANT_URL="http://localhost:6333" \
OLLAMA_URL="http://localhost:11434" \
EMBEDDING_MODEL="bge-m3" \
FASTMCP_PORT=8000 \
uv run --with fastmcp --with qdrant-client --with httpx \
  python server.py --transport sse

Then in Cursor/Windsurf MCP settings, connect to: http://localhost:8000/sse

Generic MCP client (stdio)

The default transport is stdio. Any MCP client that supports stdio can use this server by running:

uv run --with fastmcp --with qdrant-client --with httpx python server.py

---

Configuration Reference

MCP Server Environment Variables

Variable	Description	Default
QDRANT_URL	Qdrant server URL	http://localhost:6333
QDRANT_API_KEY	API key for Qdrant Cloud	None
OLLAMA_URL	Ollama server URL	http://localhost:11434
EMBEDDING_MODEL	Ollama embedding model name	bge-m3
COLLECTION_NAME	Default collection (empty = must specify per call)	(empty)

Choosing an Embedding Model

All models below are available via ollama pull <model>:

Model	Dimensions	Size	Speed	Quality	Best for
bge-m3	1024	1.2 GB	Moderate	High	General purpose, multilingual
nomic-embed-text	768	274 MB	Fast	Good	Lightweight, English-focused
mxbai-embed-large	1024	670 MB	Moderate	High	English, high quality
snowflake-arctic-embed2	1024	1.2 GB	Moderate	Very High	Best quality, English
all-minilm	384	46 MB	Very Fast	Fair	Minimal resources

Recommendation: Start with bge-m3. It handles code well, supports multilingual content (comments in any language), and balances quality with speed.

Important: The embedding model used to index a collection must match the model used for queries. If you re-embed with a different model, delete and recreate the collection.

GPU Utilization

Larger models use more GPU. If your GPU is underutilized:

• Switch from nomic-embed-text (274 MB) to bge-m3 (1.2 GB) or larger
• The embedding script sends all texts in a single batch to maximize GPU saturation
• For individual queries (via qdrant_find), GPU spikes are brief and normal — embedding a single query takes milliseconds

Check GPU usage: nvidia-smi (NVIDIA) or rocm-smi (AMD)

---

MCP Tools

qdrant_store

Store information in the Qdrant database.

Parameter	Type	Required	Description
information	string	Yes	Text to store and make searchable
collection_name	string	If no default set	Target collection
metadata	dict	No	Optional metadata to attach

qdrant_find

Search for relevant information using semantic similarity.

Parameter	Type	Required	Description
query	string	Yes	Natural language search query
collection_name	string	If no default set	Collection to search
top_k	int	No	Max results to return (default: 5)

---

Troubleshooting

"Connection closed" / MCP server won't start

• Is Ollama running? Check with ollama list. Start it with ollama serve if needed.
• Is the embedding model pulled? Run ollama pull bge-m3.
• Is Qdrant running? Check with docker ps --filter name=qdrant-server.

"Collection does not exist"

The collection is created by the embedding script or on first qdrant_store call. Either:

• Run embed_codebase.py to index your codebase first
• Or store something with qdrant_store to auto-create the collection

Dimension mismatch errors

This happens when the collection was created with one embedding model but you're querying with another. Fix:

1. Delete the collection: visit http://localhost:6333/dashboard
2. Re-embed with the correct model
3. Ensure EMBEDDING_MODEL in the MCP server config matches what you used for embedding

"Storage folder is already accessed by another instance"

This error comes from the official mcp-server-qdrant using local mode (QDRANT_LOCAL_PATH). This project avoids that by connecting to a Qdrant server via URL. Make sure you're not running both servers pointing to the same local path.

Slow embedding / low GPU utilization

• Use a larger model: bge-m3 (1.2 GB) instead of nomic-embed-text (274 MB)
• The embedding script sends all texts in one batch — if you have thousands of chunks, this maximizes GPU usage
• For very large codebases (10,000+ files), consider splitting into multiple runs per directory

---

License

Apache License 2.0 — see LICENSE.