# MCP RAG Server
An MCP (Model Context Protocol) server that exposes RAG capabilities to Claude Code and other MCP clients.
> *This is a standalone extraction from my production portfolio site. See it in action at [danmonteiro.com](https://www.danmonteiro.com).*
---
## The Problem
You're using Claude Code but:
- **No access to your documents** — Claude can't search your knowledge base
- **Context is manual** — you're copy-pasting relevant docs into prompts
- **RAG is disconnected** — your vector database isn't accessible to AI tools
- **Integration is custom** — every project builds its own RAG bridge
## The Solution
MCP RAG Server provides:
- **Standard MCP interface** — works with Claude Code, Claude Desktop, and any MCP client
- **Full RAG pipeline** — hybrid search, query expansion, semantic chunking built-in
- **Simple tools** — `rag_query`, `rag_search`, `index_document`, `get_stats`
- **Zero config** — point at ChromaDB and go
```bash
# In Claude Code, after configuring the server:
"Search my knowledge base for articles about RAG architecture"
# Claude automatically uses rag_query tool and gets relevant context
```
## Results
From production usage:
| Without MCP RAG | With MCP RAG |
|-----------------|--------------|
| Manual context copy-paste | Automatic retrieval |
| No document search | Hybrid search built-in |
| Static knowledge | Live vector database |
| Custom integration per project | Standard MCP protocol |
---
## Design Philosophy
### Why MCP?
MCP (Model Context Protocol) standardizes how AI applications connect to external tools:
```
┌──────────────┐ MCP Protocol ┌──────────────┐
│ MCP Client │◀────────────────────▶│ MCP Server │
│ (Claude Code)│ │ (This repo) │
└──────────────┘ └──────────────┘
│
┌──────▼──────┐
│ RAG Pipeline │
│ (ChromaDB) │
└─────────────┘
```
Instead of building custom integrations, MCP provides a universal interface that any MCP-compatible client can use.
### Tools Exposed
| Tool | Description |
|------|-------------|
| `rag_query` | Query with hybrid search, returns formatted context |
| `rag_search` | Raw similarity search, returns chunks with scores |
| `index_document` | Add a single document |
| `index_documents_batch` | Batch index multiple documents |
| `delete_by_source` | Delete all docs from a source |
| `get_stats` | Collection statistics |
| `clear_collection` | Clear all data (requires confirmation) |
---
## Quick Start
### 1. Prerequisites
```bash
# Start ChromaDB
docker run -p 8000:8000 chromadb/chroma
# Set OpenAI API key (for embeddings)
export OPENAI_API_KEY="sk-..."
```
### 2. Install & Build
```bash
git clone https://github.com/0xrdan/mcp-rag-server.git
cd mcp-rag-server
npm install
npm run build
```
### 3. Configure Claude Code
Add to your Claude Code MCP configuration (`~/.claude/mcp.json` or project `.mcp.json`):
```json
{
"mcpServers": {
"rag": {
"command": "node",
"args": ["/path/to/mcp-rag-server/dist/server.js"],
"env": {
"OPENAI_API_KEY": "sk-...",
"CHROMA_URL": "http://localhost:8000",
"CHROMA_COLLECTION": "my_knowledge_base"
}
}
}
}
```
### 4. Use in Claude Code
```bash
# Restart Claude Code to load the server
claude
# Now Claude has access to RAG tools:
"Index this document into my knowledge base: [paste content]"
"Search for information about transformer architectures"
"What do my docs say about error handling?"
```
---
## API Reference
### rag_query
Query the knowledge base with hybrid search. Returns formatted context suitable for LLM prompts.
```typescript
// Input
{
question: string; // Required: the question to search for
topK?: number; // Optional: number of results (default: 5)
threshold?: number; // Optional: min similarity 0-1 (default: 0.5)
filters?: object; // Optional: metadata filters
}
// Output
{
context: string; // Formatted context for LLM
chunks: [{
content: string;
score: number;
metadata: object;
}];
stats: {
totalChunks: number;
avgSimilarity: number;
};
}
```
### rag_search
Raw similarity search without context formatting.
```typescript
// Input
{
query: string; // Required: search query
topK?: number; // Optional: number of results (default: 10)
filters?: object; // Optional: metadata filters
}
// Output: Array of chunks with scores
```
### index_document
Add a document to the knowledge base.
```typescript
// Input
{
id: string; // Required: unique identifier
title: string; // Required: document title
content: string; // Required: document content
source: string; // Required: source identifier
category?: string; // Optional: category
tags?: string[]; // Optional: tags array
}
// Output
{
success: boolean;
documentId: string;
chunksIndexed: number;
}
```
### get_stats
Get collection statistics.
```typescript
// Output
{
totalChunks: number;
totalDocuments: number;
// ... other stats from RAG pipeline
}
```
---
## Configuration
### Environment Variables
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `OPENAI_API_KEY` | Yes | - | OpenAI API key for embeddings |
| `CHROMA_URL` | No | `http://localhost:8000` | ChromaDB URL |
| `CHROMA_COLLECTION` | No | `mcp_knowledge_base` | Collection name |
| `EMBEDDING_MODEL` | No | `text-embedding-3-large` | Embedding model |
| `EMBEDDING_DIMENSIONS` | No | Native | Reduced dimensions |
---
## Project Structure
```
mcp-rag-server/
├── src/
│ ├── server.ts # Main MCP server implementation
│ └── index.ts # Exports
├── mcp-config.example.json # Example Claude Code configuration
├── package.json
└── README.md
```
---
## Advanced Usage
### Programmatic Server Creation
```typescript
import { createServer } from 'mcp-rag-server';
const server = await createServer({
vectorDB: {
host: 'http://custom-chroma:8000',
collectionName: 'my_collection',
},
rag: {
topK: 10,
enableHybridSearch: true,
},
});
```
### Using with Claude Desktop
Same configuration works with Claude Desktop's MCP support:
```json
// ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
{
"mcpServers": {
"rag": {
"command": "node",
"args": ["/path/to/mcp-rag-server/dist/server.js"]
}
}
}
```
---
## Part of the Context Continuity Stack
This repo exposes **context continuity as a protocol-level capability** — giving any MCP client access to persistent semantic memory.
| Layer | Role | This Repo |
|-------|------|-----------|
| Intra-session | Short-term memory | — |
| Document-scoped | Injected content | — |
| **Retrieved** | **Long-term semantic memory via MCP** | **mcp-rag-server** |
| Progressive | Staged responses | — |
MCP RAG Server bridges the gap between vector databases and AI assistants. Instead of building custom integrations, any MCP-compatible tool (Claude Code, Claude Desktop, custom clients) gets instant access to your knowledge base.
**Related repos:**
- [rag-pipeline](https://github.com/0xrdan/rag-pipeline) — The underlying RAG implementation
- [mcp-client-example](https://github.com/0xrdan/mcp-client-example) — Reference client for connecting to this server
- [chatbot-widget](https://github.com/0xrdan/chatbot-widget) — Session cache, Research Mode, conversation export
- [ai-orchestrator](https://github.com/0xrdan/ai-orchestrator) — Multi-model LLM routing
---
## Contributing
Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch (`git checkout -b feat/add-new-tool`)
3. Make changes with semantic commits
4. Open a PR with clear description
---
## License
MIT License - see [LICENSE](LICENSE) for details.
---
## Acknowledgments
Built with [Claude Code](https://claude.ai/code).
```
Co-Authored-By: Claude <noreply@anthropic.com>
```
