What the rag MCP server does
The rag MCP server indexes local document collections and makes them searchable through MCP. It supports DOCX, HWPX, PDF, Excel, PowerPoint, and audio files. Scanned PDFs can use Tesseract OCR, while audio transcription uses Whisper.net on Windows. The resulting knowledge bases are stored locally and can be served together from one base path.
Search combines BM25 keyword matching and vector similarity with Reciprocal Rank Fusion. It also supports BM25-only operation when no embedding provider is configured. Korean-oriented chunking, FTS5 trigram matching, and optional bilingual enrichment help with Korean, English, CJK, substring, and cross-language queries.
How the rag MCP server works
The indexing pipeline extracts content, divides it into roughly 1,000-character chunks, optionally contextualizes each chunk with an LLM, generates embeddings, and writes the results to SQLite. Original chunk text remains available for display, while contextualized text can be used for indexing and embedding. Hash-based change detection avoids repeating work for unchanged files.
A two-commit process saves extracted and enriched chunks before embedding completes. If an embedding request fails, later retries can use the saved chunks without repeating OCR, transcription, or contextualization. Individual oversized or invalid chunks can be isolated, allowing other chunks from the same file to remain searchable.
The MCP service uses SQLite WAL mode, so searches can continue while indexing runs. Reindex requests are queued and merged by scope; a separate queue executor processes deferred work sequentially to avoid concurrent indexing contention.
Setup and configuration
Run the serve command with a base path containing knowledge bases. The service uses standard MCP stdio transport and accepts a kb_id parameter for multi-KB operations. Each knowledge base has a config.json containing provider settings.
Embedding and contextualization can use Ollama, OpenAI-compatible endpoints, Gemini, or Anthropic for the supported roles. OpenAI-compatible configurations can target OpenAI, Azure OpenAI, Groq, LM Studio, or Together AI. Provider credentials are supplied through environment variables such as OPENAI_API_KEY or ANTHROPIC_API_KEY; the exact variables depend on the configured provider. Batch commands use environment variables, while interactive MCP search may use MCP elicitation when the client supports it.
Use exec for headless indexing of one knowledge base, exec-queue for deferred queue processing, prune-orphans to remove unconfigured knowledge-base folders, and smoke-ocr to test scanned-PDF OCR on Windows.
Tools and capabilities
The rag MCP server exposes these MCP tools:
list_knowledge_bases reports available knowledge bases, file and chunk counts, and indexing status.search_documents runs automatic, BM25, or vector search.get_document_chunk returns the complete content for a chunk ID.start_reindex queues indexing with merge, force, and deferred options.cancel_reindex removes a queued request that has not started.get_index_info reports index metadata, queue position and status, errors, and contextualization health.check_changes performs a lightweight filesystem scan without API calls.
Limitations and notes
Audio transcription is Windows-only, and OCR depends on the native OCR setup. Large scanned documents and long recordings may take substantial time during extraction; the first audio file may also require a one-time Whisper model download. The contextualization stage is optional, but embeddings require a configured provider for vector search.
The service is read-only at the MCP serving layer; indexing is managed through the command-line pipeline and queued reindex operations. Failed or deferred chunks may leave a knowledge base in a partial or degraded state until retries succeed. The project is distributed under the MIT license.