Enhanced Qdrant MCP Server for Claude Code

This repository contains an enhanced version of the Qdrant MCP server with support for multiple embedding providers, making it more flexible for use with Claude Code as a semantic memory system.

Features

• Multiple Embedding Providers:

  • FastEmbed - The original lightweight embedding provider with ONNX Runtime
  • GGUF - Direct integration with GGUF-format embedding models via llama.cpp
  • LM Studio - Connectivity to LM Studio's API for optimized local embedding generation

• Docker Compose Setup:

  • Complete stack with Qdrant database, MCP servers, and UI
  • Multiple MCP server instances for different providers
  • Easy configuration through environment variables

• Comprehensive Makefile:

  • Simple commands for building, starting, and managing the stack
  • Tools for adding different MCP configurations to Claude Code
  • Utilities for downloading models and dependencies

Quick Start

Prerequisites

• Docker and Docker Compose
• Python 3.8+ with pip
• For GGUF: llama.cpp embedding binary
• For LM Studio: LM Studio application

Installation

1. Clone and set up:

   cd /Users/oliviercontant/Sandbox/AI/mcp/qdrant
   make install-deps
   

2. Start with FastEmbed (simplest option):

   make start-fastembed
   

3. Add to Claude Code:

   make add-to-claude  # For GGUF provider
   # OR
   make add-lmstudio-to-claude  # For LM Studio provider
   

Using Different Embedding Providers

FastEmbed (Default)

The original provider that uses lightweight ONNX Runtime for generating embeddings:

# Run with Docker
make start-fastembed

# Run locally
make run-fastembed

# Add to Claude Code
claude mcp add qdrant-fastembed \
  -e QDRANT_URL="http://localhost:6333" \
  -e COLLECTION_NAME="code-memory" \
  -e EMBEDDING_PROVIDER="fastembed" \
  -e EMBEDDING_MODEL="sentence-transformers/all-MiniLM-L6-v2" \
  -- uvx mcp-server-qdrant

GGUF Models

Use quantized GGUF embedding models for efficient memory usage:

# Run with Docker
make start-gguf

# Run locally
make run-gguf

# Add to Claude Code with custom model
make add-to-claude MODEL_NAME=all-MiniLM-L6-v2-Q8_0.gguf HUGGINGFACE_REPO=TheBloke/all-MiniLM-L6-v2-GGUF

For more details, see GGUF Support Documentation.

LM Studio

Connect to LM Studio for optimized local embedding generation:

# Start LM Studio and load your embedding model first

# Run with Docker
make start-lmstudio

# Run locally
make run-lmstudio

# Add to Claude Code with custom settings
make add-lmstudio-to-claude LMSTUDIO_API_BASE=http://localhost:1234/v1 LMSTUDIO_MODEL=Snowflake/snowflake-arctic-embed-l-v2.0 LMSTUDIO_VECTOR_SIZE=768

For more details, see LM Studio Support Documentation.

Environment Variables

Each embedding provider has its own set of environment variables:

Common Variables

• QDRANT_URL - URL of the Qdrant server
• COLLECTION_NAME - Name of the Qdrant collection
• EMBEDDING_PROVIDER - Provider type (fastembed, gguf, or lmstudio)
• EMBEDDING_MODEL - Model name or path
• EMBEDDING_VECTOR_SIZE - Size of embedding vectors (optional)

GGUF-specific Variables

• LLAMA_CPP_PATH - Path to llama.cpp embedding binary
• EMBEDDING_MAX_CONTEXT_LENGTH - Maximum context length for embeddings

LM Studio-specific Variables

• LMSTUDIO_API_BASE - Base URL of the LM Studio API
• LMSTUDIO_API_KEY - API key for authentication (optional)

Using with Claude Code

1. Start the Qdrant server:

   make start
   

2. Add to Claude Code:

   # Choose one provider:
   make add-to-claude  # GGUF
   # OR
   make add-lmstudio-to-claude  # LM Studio
   

3. Verify in Claude Code:

   claude mcp list
   

Troubleshooting

• Connection issues: Ensure Qdrant is running (make start)
• GGUF model errors: Check that llama.cpp is properly installed (make download-llama-cpp)
• LM Studio errors: Verify LM Studio is running with your model loaded (make check-lmstudio)

Advanced Usage

See the Makefile for more commands:

make help

Additional Documentation

• GGUF Support Documentation
• LM Studio Support Documentation
• Original Qdrant MCP Server Documentation