🌉 mcp-rag-bridge

Connect any AI agent to your document knowledge base via MCP (Model Context Protocol).

This server wraps a RAG (Retrieval-Augmented Generation) pipeline as MCP tools — so Claude, Qwen Code, or any MCP client can query your documents, add new ones, and get grounded answers with citations.

Why this exists

"A RAG pipeline without an agent interface is just a search engine. An agent without RAG is just a chatbot. The bridge makes both smarter."

This project connects the two worlds: your documents become the agent's knowledge, and the agent becomes the interface to that knowledge.

Architecture

┌─────────────────────┐
│   MCP Client (AI)   │
│  Claude / Qwen Code │
└──────────┬──────────┘
           │ stdio (JSON-RPC)
┌──────────▼──────────┐
│   MCP RAG Bridge    │
│                     │
│  query_kb ──────────────┐
│  add_document ─────┐    │
│  list_sources ──┐  │    │
│  delete_doc ─┐  │  │    │
│  search ──┐  │  │  │    │
└──────────┼──┼──┼──┼────┘
           │  │  │  │
     ┌─────▼──▼──▼──▼────┐
     │   ChromaDB +      │
     │   Embeddings      │
     └───────────────────┘

Tools (6)

Tool	What it does
query_knowledge_base	Search documents + optional LLM-generated answer with citations
list_sources	List all indexed documents with chunk counts
add_document	Index a file (txt, md, pdf, csv, json) into the knowledge base
add_text	Index raw text (notes, snippets, API responses)
delete_document	Remove a document from the knowledge base
search_similar	Find documents similar to a given text

Quick start

git clone https://github.com/zyay/mcp-rag-bridge.git
cd mcp-rag-bridge
python -m venv venv && venv\Scripts\activate
pip install -r requirements.txt

# Start the MCP server
python server.py

# Or test with the included client
python client_test.py

Connect an MCP client

Qwen Code

qwen mcp add rag-bridge -- python /full/path/to/mcp-rag-bridge/server.py

Claude Code

claude mcp add rag-bridge -- python /full/path/to/mcp-rag-bridge/server.py

Claude Desktop

{
  "mcpServers": {
    "rag-bridge": {
      "command": "python",
      "args": ["/full/path/to/mcp-rag-bridge/server.py"]
    }
  }
}

Usage examples

Once connected, the agent can interact with your knowledge base naturally:

User: "What documents do you know about?"
Agent: [calls list_sources()]

User: "Index the file at ./docs/architecture.md"
Agent: [calls add_document("./docs/architecture.md")]

User: "How does our authentication system work?"
Agent: [calls query_knowledge_base("authentication system", use_llm=True)]

User: "Find documents similar to 'database migration strategy'"
Agent: [calls search_similar("database migration strategy")]

LLM generation

Set use_llm=True in query_knowledge_base to get grounded answers:

• Ollama (default): Local, free, no API key. Set OLLAMA_MODEL=llama3.2.
• OpenAI fallback: Set LLM_PROVIDER=openai and OPENAI_API_KEY=sk-...

The bridge tries the primary provider first, then falls back automatically.

Environment variables

Variable	Default	Description
RAG_DATA_DIR	data	Document directory
RAG_CHROMA_DIR	.chroma	Vector store path
RAG_COLLECTION	docs	ChromaDB collection name
RAG_CHUNK_SIZE	600	Text chunk size (chars)
RAG_CHUNK_OVERLAP	120	Overlap between chunks
LLM_PROVIDER	ollama	LLM provider (ollama/openai)
OLLAMA_URL	http://localhost:11434	Ollama server URL
OLLAMA_MODEL	llama3.2	Ollama model name
OPENAI_API_KEY	(empty)	OpenAI API key
OPENAI_MODEL	gpt-4o-mini	OpenAI model name

Design decisions

Decision	Why
Self-contained	No dependency on rag-docs-assistant — works as a standalone project
Hybrid search	70% semantic + 30% lexical for better recall
Two-step LLM	Retrieve first, then generate — grounded answers with citations
ChromaDB	Zero-config, persistent, no separate server needed
stdio transport	Works with any MCP client, no HTTP server needed

Relationship to other projects

• rag-docs-assistant — Full RAG pipeline with web UI, evals, reranking. This project shares the same core concepts but is self-contained.
• mcp-agent-tools — General-purpose MCP tools (file, MySQL, web, calc). This project is the RAG-specific counterpart.

Together, these three projects demonstrate a complete AI agent ecosystem: general tools + knowledge retrieval + the bridge between them.

License

MIT