shinpr/mcp-local-rag

English |
简体中文 |
Deutsch |
Español |
Português (Brasil) |
Français
Search private documents from an MCP client or the terminal without sending them to an
embedding API.
mcp-local-rag indexes PDF, DOCX, Markdown, and text files on your machine. Search combines
semantic similarity with keyword matching, so queries can match both intent and exact technical
terms such as API names, class names, and error codes. Results include source passages and,
where available, headings, line numbers, or page numbers so you can check and cite the original
document.
No API key, Docker, Python, or external database is required. After the initial model download,
text ingestion and search work offline.
Quick Start
Requirements
- Node.js 22 or later
- Internet access on first use to download the npm package and embedding model
- A directory containing the documents you want to search
Set BASE_DIR to that directory. It is also the security boundary for file operations. Replace
/absolute/path/to/your/documents below with the directory's absolute path.
Use one of the examples below, or register npx -y mcp-local-rag and set BASE_DIR using your
client's MCP configuration format.
Set DB_PATH and CACHE_DIR to absolute paths as well. Relative paths resolve from the
server's working directory, so starting the server from different projects creates a separate
index and model cache in each.
Claude Code
Run this command:
Codex
Add to ~/.codex/config.toml:
OpenCode
Add to ~/.config/opencode/opencode.json (or opencode.jsonc):
Cursor
Add to ~/.cursor/mcp.json:
Restart the client, then ask it to build the index:
The first sync downloads the default embedding model (about 90 MB) and may take 1–2 minutes
before ingestion starts. Later runs use the local cache.
Once the sync completes:
CLI Quick Start
To use the CLI without an MCP client:
The CLI uses the current directory as its document root by default. Run both commands from the
same directory so they use the same default index, or set BASE_DIR and DB_PATH explicitly.
Supported Content
| Input | How to ingest |
|---|---|
| PDF, DOCX, TXT, Markdown | File ingestion or directory sync |
| HTML already fetched by the client | ingest_data |
| Plain text or Markdown held in memory | ingest_data with a stable source identifier |
HTML fetching is not built into the server. An MCP client can fetch a page and pass its HTML to
ingest_data.
Excel, PowerPoint, standalone images, and source-code file extensions are not supported by file
ingestion. PDFs can optionally use a local vision model to describe figures, but this is not
OCR or image search.
Using the Index
Sync after adding, editing, or removing documents. For searches and follow-up reading, ask your
MCP client:
You can also ingest a single file or HTML already fetched by the client. To refresh an existing
entry, ingest the document again using the same path or source identifier. sync skips unchanged
files. MCP file paths must be absolute and inside a configured document root.
PDF section headings may be inaccurate. Check the original page when you need the exact heading.
MCP Tools
| Tool | Purpose |
|---|---|
| sync_start | Reconcile the index with all configured roots or one path |
| sync_status | Poll a running sync job |
| ingest_file | Ingest or replace one file |
| ingest_data | Ingest text, Markdown, or HTML already held by the client |
| query_documents | Search with semantic matching and keyword boost |
| read_chunk_neighbors | Read surrounding chunks from a search result |
| list_files | Show supported files and their ingestion state |
| delete_file | Delete an indexed file or an ingest_data item |
| status | Show index and search status |
CLI
Use the CLI to update the index, narrow searches, or remove indexed content:
ingest imports the selected files; sync also removes entries for deleted files and skips
unchanged files. Use --scope to restrict search results to a path prefix, repeating it to
include multiple prefixes.
Global options such as --db-path, --cache-dir, and --model-name go before the subcommand.