Skip to main content
Glama
justinlime

Easy MCP RAG

by justinlime
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Easy MCP RAG 🚀

A high-performance Model Context Protocol (MCP) server for RAG using Qdrant. Built for UV/UVX with CPU/GPU support and HTTP transport.

✨ Features

  • 🔍 Automatic Document Indexing - Scan directories and index all documents

  • 📁 Smart Organization - Each subdirectory becomes its own searchable dataset

  • 🛠️ Dynamic MCP Tools - Auto-generated tools for each collection

  • 📄 Multi-Format Support - PDF, DOCX, CSV, XLSX, TXT, Markdown, and more

  • ⚡ GPU Acceleration - Optional CUDA/MPS support for faster embeddings

  • 🌐 HTTP Transport - Run as HTTP server or stdio

  • 📦 UV/UVX Ready - Install and run with a single command

  • 📊 Verbose Logging - Detailed query tracking and monitoring

Related MCP server: mcp-rag-server

🚀 Quick Start

Install with UVX (Recommended)

Run directly from GitHub without installation:

uvx --from git+https://github.com/yourusername/easy_mcp_rag.git easy_mcp_rag --data-dir ./documents

Install with UV

# Install from GitHub
uv pip install git+https://github.com/yourusername/easy_mcp_rag.git

# Or clone and install locally
git clone https://github.com/yourusername/easy_mcp_rag.git
cd easy_mcp_rag
uv pip install -e .

📋 Prerequisites

  1. Start Qdrant (using Docker):

docker run -p 6333:6333 qdrant/qdrant

  1. Prepare your documents:

documents/
├── legal_docs/
│   ├── contract.pdf
│   └── terms.docx
├── research/
│   ├── paper1.pdf
│   └── notes.txt
└── data/
    └── analysis.csv

💻 Usage

Basic Usage (stdio)

# With UVX
uvx --from git+https://github.com/yourusername/easy_mcp_rag.git easy_mcp_rag --data-dir ./documents

# With UV
uv run easy_mcp_rag --data-dir ./documents

# After installation
easy_mcp_rag --data-dir ./documents

HTTP Mode

easy_mcp_rag --data-dir ./documents --transport http --http-port 8000

GPU Acceleration

# Auto-detect GPU
easy_mcp_rag --data-dir ./documents --device auto

# Force CUDA (NVIDIA GPU)
easy_mcp_rag --data-dir ./documents --device cuda

# Force MPS (Apple Silicon)
easy_mcp_rag --data-dir ./documents --device mps

# Force CPU
easy_mcp_rag --data-dir ./documents --device cpu

Advanced Configuration

easy_mcp_rag \
  --data-dir ./documents \
  --qdrant-host localhost \
  --qdrant-port 6333 \
  --device cuda \
  --embedding-model all-mpnet-base-v2 \
  --chunk-size 1024 \
  --chunk-overlap 100 \
  --top-k 10 \
  --batch-size 64 \
  --verbose \
  --force-reindex

🔧 Configuration Options

Flag

Description

Default

--data-dir

Directory with document subdirectories

Required

--qdrant-host

Qdrant server host

localhost

--qdrant-port

Qdrant server port

6333

--device

Device: auto, cpu, cuda, mps

auto

--transport

Transport type: stdio, http

stdio

--http-host

HTTP server host

0.0.0.0

--http-port

HTTP server port

8000

--embedding-model

Sentence transformer model

all-MiniLM-L6-v2

--chunk-size

Text chunk size (chars)

512

--chunk-overlap

Chunk overlap (chars)

50

--top-k

Results per search

5

--batch-size

Embedding batch size

32

--verbose

Enable verbose logging

False

--log-level

Log level

INFO

--force-reindex

Force reindex all docs

False

🎯 MCP Client Configuration

Claude Desktop / Cline / Other MCP Clients

Add to your MCP client config:

{
  "mcpServers": {
    "rag-server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/yourusername/easy_mcp_rag.git",
        "easy_mcp_rag",
        "--data-dir",
        "/path/to/your/documents",
        "--device",
        "auto",
        "--verbose"
      ]
    }
  }
}

With HTTP Transport

{
  "mcpServers": {
    "rag-server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/yourusername/easy_mcp_rag.git",
        "easy_mcp_rag",
        "--data-dir",
        "/path/to/your/documents",
        "--transport",
        "http",
        "--http-port",
        "8000"
      ]
    }
  }
}

🛠️ How It Works

  1. Scan - Discovers all subdirectories in your data directory

  2. Load - Extracts text from all supported file types

  3. Chunk - Splits documents into overlapping chunks

  4. Embed - Generates vector embeddings (CPU or GPU)

  5. Index - Stores in Qdrant (one collection per subdirectory)

  6. Serve - Creates MCP tools for each collection

Example

documents/
├── legal_docs/      → Creates "legal_docs_search" tool
├── research/        → Creates "research_search" tool
└── data/            → Creates "data_search" tool

📄 Supported File Types

Category

Extensions

Text

.txt, .md, .py, .js, .json, .xml, .html, .css

PDF

.pdf

Word

.docx, .doc

Spreadsheet

.csv, .xlsx, .xls

🎨 Embedding Models

Choose based on your needs:

Model

Dimensions

Speed

Quality

Use Case

all-MiniLM-L6-v2

384

⚡⚡⚡

Good

Default, fast

all-MiniLM-L12-v2

384

⚡⚡

Better

Balanced

all-mpnet-base-v2

768

⚡

Best

Quality

🐛 Troubleshooting

Qdrant Connection Failed

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

# Start Qdrant
docker run -p 6333:6333 qdrant/qdrant

GPU Not Detected

# Check PyTorch GPU support
python -c "import torch; print(torch.cuda.is_available())"

# Install with GPU support
uv pip install -e ".[gpu]"

Out of Memory

# Use smaller model
--embedding-model all-MiniLM-L6-v2

# Reduce batch size
--batch-size 16

# Use CPU
--device cpu

📊 Logging

Enable verbose logging to see detailed information:

easy_mcp_rag --data-dir ./documents --verbose

Output includes:

  • ✅ Tool access events

  • 🔍 Query details

  • 📈 Result counts

  • 🎯 Relevance scores

  • 📁 Source files

Example:

2024-01-20 10:30:15 - easy_mcp_rag.server - INFO - Tool accessed: legal_docs_search
2024-01-20 10:30:15 - easy_mcp_rag.server - INFO - Query: contract terms
2024-01-20 10:30:15 - easy_mcp_rag.server - INFO - Results returned: 5
2024-01-20 10:30:15 - easy_mcp_rag.server - DEBUG - Result 1: score=0.8542

🔐 Security Notes

  • HTTP mode exposes the server on the network

  • Use --http-host 127.0.0.1 for local-only access

  • Consider authentication for production deployments

📝 Development

# Clone repository
git clone https://github.com/yourusername/easy_mcp_rag.git
cd easy_mcp_rag

# Install with dev dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# Format code
black src/

# Lint
ruff src/

🤝 Contributing

Contributions welcome! Please:

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Submit a pull request

📜 License

MIT License - see LICENSE file

🙏 Credits

Built with:

This server cannot be deployed

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Tiny Chat

    to-aoki
    A
    license
    D
    quality
    C
    maintenance
    A lightweight RAG system that provides an MCP server for searching and interacting with vector-based knowledge bases. It enables users to perform retrieval-augmented generation and search across Qdrant collections through a standardized interface.
    1
    2
    MIT

  • mcp-rag-server

    kwanLeeFrmVi
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that indexes documents and serves relevant context to LLMs via Retrieval Augmented Generation (RAG).
    28
    37
    MIT

  • THE RAG MCP

    Sankalp-2005
    F
    license
    Not graded
    quality
    D
    maintenance
    An enterprise-ready MCP server that exposes a RAG tool for retrieving relevant context and metadata from a Qdrant vector database using natural language queries.
    2
    -