Py MCP Server with Qdrant RAG

Overview

Py MCP Server with Qdrant RAG is a lightweight reference implementation that combines a Model Context Protocol (MCP) server with Qdrant vector search to enable Retrieval-Augmented Generation (RAG). It makes it simple to ingest documents, generate embeddings (locally or via cloud APIs), and run semantic search or document retrieval from Mac, Linux, or Windows environments.

This setup is useful for developers building knowledge-enabled assistants, semantic search endpoints, or RAG pipelines that need fast vector similarity search and flexible embedding backends. Qdrant provides a scalable vector database; the MCP server exposes a consistent API surface so models and tools can request context vectors and metadata for downstream use.

Features

• Semantic search backed by Qdrant vector store (local or cloud)
• Support for local embeddings (sentence-transformers) or cloud embeddings (OpenAI)
• Simple MCP-compatible HTTP API for retrieval and context assembly
• Platform-agnostic: runs on macOS, Linux, and Windows
• Docker examples for quick local Qdrant launch
• Configurable via environment variables and .env files

Installation / Configuration

Prerequisites:

• Python 3.10+ (or the version documented in the repo)
• Docker (optional, for running Qdrant locally)
• (Optional) OpenAI API key if using cloud embeddings

Clone the repo and create a virtual environment:

git clone https://github.com/amornpan/py-mcp-qdrant-rag.git
cd py-mcp-qdrant-rag
python -m venv .venv
source .venv/bin/activate   # macOS / Linux
# .venv\Scripts\activate    # Windows (PowerShell)

Install dependencies (either from requirements.txt or core packages):

pip install -r requirements.txt
# or
pip install fastapi uvicorn qdrant-client sentence-transformers python-dotenv openai

Run Qdrant locally with Docker (default port 6333):

docker run -p 6333:6333 qdrant/qdrant

Create a .env file (example):

# Qdrant
QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=

# Collection settings
QDRANT_COLLECTION=documents

# Embedding provider: "local" or "openai"
EMBEDDING_PROVIDER=local

# If using OpenAI for embeddings
OPENAI_API_KEY=sk-...

# Server
MCP_HOST=0.0.0.0
MCP_PORT=8000

Start the MCP server (example using uvicorn):

uvicorn app.main:app --host ${MCP_HOST:-0.0.0.0} --port ${MCP_PORT:-8000}

Adjust the import path (app.main:app) to match the server module in the repository. The server will connect to Qdrant using QDRANT_URL and store/retrieve vectors from QDRANT_COLLECTION.

Available Resources

• GitHub repository: https://github.com/amornpan/py-mcp-qdrant-rag
• Qdrant docs: https://qdrant.tech/documentation/
• OpenAI embeddings: https://platform.openai.com/docs/guides/embeddings
• SentenceTransformers (local embeddings): https://www.sbert.net/

Environment variables (summary):

Quick Examples

1. Upsert a document (pseudo-cURL; adapt to actual API endpoints in the repo):

curl -X POST "http://localhost:8000/documents" \
  -H "Content-Type: application/json" \
  -d '{"id":"doc1","text":"The Eiffel Tower is in Paris.","metadata":{"source":"wiki"}}'

The server will compute embeddings (local or OpenAI) and store them in Qdrant.

2. Semantic search:

curl -X POST "http://localhost:8000/search" \
  -H "Content-Type: application/json" \
  -d '{"query":"Where is the Eiffel Tower?","top_k":5}'

Response contains the top-k matching documents with similarity scores and metadata suitable for RAG context assembly.

3. Use local embeddings (Python snippet example):

from sentence_transformers import SentenceTransformer
model = SentenceTransformer("all-MiniLM-L6-v2")
emb = model.encode(["text to embed"])[0]

When EMBEDDING_PROVIDER=local, the MCP server will use a similar model under the hood.

Use Cases

• Knowledge-enabled chatbot: retrieve relevant documents from a company wiki to provide accurate answers, then pass retrieved context to a language model for generation.
• Semantic search portal: replace keyword search with vector search for better relevance and intent matching.
• Document clustering and filtering: use Qdrant similarity queries to group related content and build discovery UIs.
• Augment LLM prompts: dynamically assemble context passages (RAG) to reduce hallucination and improve factuality.

Concrete scenario:

• A customer support tool ingests product manuals into Qdrant.