![\"MCP](\"assets/banner.jpg\")
\n\n \n
\n English |\n 简体中文 |\n Deutsch |\n Español |\n Português (Brasil) |\n Français\n
\n\nSearch private documents from an MCP client or the terminal without sending them to an\nembedding API.\n\nmcp-local-rag indexes PDF, DOCX, Markdown, and text files on your machine. Search combines\nsemantic similarity with keyword matching, so queries can match both intent and exact technical\nterms such as API names, class names, and error codes.\n\n## Features\n\n- **Runs locally:** Document parsing, embeddings, storage, and search run on your machine.\n After the initial model download, text ingestion and search work offline.\n- **Hybrid search:** Semantic retrieval finds related concepts, while keyword matching boosts\n exact technical terms.\n- **Configurable embeddings:** Choose a Hugging Face embedding model that fits the language and\n domain of your documents.\n- **Semantic chunking:** Documents are split at topic boundaries instead of fixed character\n counts. Markdown code blocks stay intact.\n- **MCP and CLI:** Use the same index from an AI coding tool or directly from the terminal.\n\nNo API key, Docker, Python, or external database is required.\n\n## Quick Start\n\n### Requirements\n\n- Node.js 22 or later\n- Internet access on first use to download the npm package and embedding model\n- A directory containing the documents you want to search\n\nSet `BASE_DIR` to that directory. It is also the security boundary for file operations. Replace\n`/absolute/path/to/your/documents` below with the directory's absolute path.\n\nmcp-local-rag uses the standard MCP protocol over a local stdio server, so it works with AI\ncoding tools and other MCP hosts that support local MCP servers.\n\nUse one of the examples below, or register `npx -y mcp-local-rag` and set `BASE_DIR` using your\nclient's MCP configuration format.\n\n**For Claude Code:** Run this command:\n\n```bash\nclaude mcp add local-rag --scope user --env BASE_DIR=/absolute/path/to/your/documents -- npx -y mcp-local-rag\n```\n\n**For Codex:** Add to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.local-rag]\ncommand = \"npx\"\nargs = [\"-y\", \"mcp-local-rag\"]\n\n[mcp_servers.local-rag.env]\nBASE_DIR = \"/absolute/path/to/your/documents\"\n```\n\n**For OpenCode:** Add to `~/.config/opencode/opencode.json` (or `opencode.jsonc`):\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"mcp\": {\n \"local-rag\": {\n \"type\": \"local\",\n \"command\": [\"npx\", \"-y\", \"mcp-local-rag\"],\n \"environment\": {\n \"BASE_DIR\": \"/absolute/path/to/your/documents\"\n }\n }\n }\n}\n```\n\n**For Cursor:** Add to `~/.cursor/mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"local-rag\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"mcp-local-rag\"],\n \"env\": {\n \"BASE_DIR\": \"/absolute/path/to/your/documents\"\n }\n }\n }\n}\n```\n\nRestart the client, then ask it to build the index:\n\n```text\nSync all documents in the configured root and wait until it finishes.\n```\n\nThe first sync downloads the default embedding model (about 90 MB) and may take 1–2 minutes\nbefore ingestion starts. Later runs use the local cache.\n\nOnce the sync completes:\n\n```text\nWhat does the API documentation say about authentication?\n```\n\n### CLI Quick Start\n\nTo use the CLI without an MCP client:\n\n```bash\nnpx mcp-local-rag ingest ./docs/\nnpx mcp-local-rag query \"authentication API\"\n```\n\nThe CLI uses the current directory as its document root by default. Run both commands from the\nsame directory so they use the same default index, or set `BASE_DIR` and `DB_PATH` explicitly.\n\n## Why This Exists\n\nSome document sets cannot be sent to a hosted embedding service because of confidentiality or\norganizational policy. Keeping the index local makes them searchable without adding a per-query\nAPI cost.\n\nSemantic search alone can miss exact identifiers that matter in technical documentation.\nKeyword reranking keeps those terms visible without giving up natural-language retrieval.\n\n## Supported Content\n\n| Input | How to ingest |\n|---|---|\n| PDF, DOCX, TXT, Markdown | File ingestion or directory sync |\n| HTML already fetched by the client | `ingest_data`; cleaned with Readability and converted to Markdown |\n| Plain text or Markdown held in memory | `ingest_data` with a stable source identifier |\n\nHTML fetching is not built into the server. An MCP client can fetch a page and pass its HTML to\n`ingest_data`.\n\nExcel, PowerPoint, standalone images, and source-code file extensions are not supported by file\ningestion. PDFs can optionally use a local vision model to describe figures, but this is not OCR\nor image search.\n\n## MCP Tools\n\n| Tool | Purpose |\n|---|---|\n| `sync_start` | Reconcile the index with all configured roots or one path |\n| `sync_status` | Poll a running sync job |\n| `ingest_file` | Ingest or replace one file |\n| `ingest_data` | Ingest text, Markdown, or HTML already held by the client |\n| `query_documents` | Search with semantic matching and keyword boost |\n| `read_chunk_neighbors` | Read surrounding chunks from a search result |\n| `list_files` | Show supported files and their ingestion state |\n| `delete_file` | Delete an indexed file or an `ingest_data` item |\n| `status` | Show index and search status |\n\n### Syncing a Document Root\n\n`sync_start` ingests new and changed files, skips byte-identical files, and removes index entries\nfor files that no longer exist:\n\n```text\nSync everything under the configured document roots and wait for completion.\n```\n\nThe tool returns a `jobId` immediately. Clients should poll `sync_status` until its state becomes\n`succeeded` or `failed`. A changed PDF keeps the visual profile it was indexed with; `sync_start`\ncannot change it. Set `STORE_IMAGES=true` in the MCP server environment to store supported PDF and\nDOCX images for new or changed files selected by sync; unchanged files remain skipped.\n\nOnly one sync job is retained by the server process. A newer job replaces a finished record, and\nrestarting the server discards it.\n\n### Ingesting One File\n\n`ingest_file` accepts PDF, DOCX, TXT, and Markdown. MCP file paths must be absolute and must stay\ninside a configured document root:\n\n```text\nIngest the document at /Users/me/docs/api-spec.pdf.\n```\n\nRe-ingesting the same path replaces its existing chunks.\n\n### Searching and Reading More Context\n\n```text\nWhat does the API documentation say about authentication?\nFind the documented behavior of ERR_CONNECTION_REFUSED.\n```\n\nResults contain the text, source path, title, chunk index, relevance score, and any images stored\non that chunk. MCP returns each image as an image content block paired with its result identity;\nCLI `query` includes an `images` array of `{ imageIndex, mimeType, data }` on every result. Pass the\n`chunkIndex` and either `filePath` or `source` from a result to `read_chunk_neighbors` when the\nanswer needs more context:\n\n```text\nRead the surrounding chunks for that authentication result.\n```\n\nBoth `query_documents` and `list_files` accept an optional absolute `scope` path prefix, or a\nlist of prefixes. A prefix matches the exact path and its descendants.\n\n### Ingesting HTML\n\nUse `ingest_data` after the MCP client fetches a page:\n\n```text\nFetch https://example.com/docs and ingest the HTML.\n```\n\nThe server extracts the main article, converts it to Markdown, and stores it under the supplied\nsource identifier. Reusing the same source updates the existing content.\n\nRespect the source site's terms and copyright when indexing external content.\n\n### PDF Visual Captions and Stored Images\n\nVisual mode adds a generated caption for figure-heavy PDF pages. It is opt-in and does not load\na vision model during normal ingestion.\n\n```text\nIngest /Users/me/docs/research-paper.pdf with visual: true.\n```\n\n```bash\nnpx mcp-local-rag ingest ./docs/research-paper.pdf --visual\n```\n\nImage storage is independent of visual captions. Set `STORE_IMAGES=true` for the MCP server, or\npass `--images` to CLI ingestion and sync:\n\n```bash\nnpx mcp-local-rag ingest ./docs/research-paper.pdf --images\nnpx mcp-local-rag sync ./docs/ --images\n```\n\nPDF storage uses detected figure/table regions. DOCX storage includes only PNG/JPEG images that\nthe existing Mammoth conversion emits as `