mcp-local-rag

Run this command:

claude mcp add local-rag --scope user --env BASE_DIR=/absolute/path/to/your/documents -- npx -y mcp-local-rag

Add to ~/.codex/config.toml:

[mcp_servers.local-rag]
command = "npx"
args = ["-y", "mcp-local-rag"]

[mcp_servers.local-rag.env]
BASE_DIR = "/absolute/path/to/your/documents"

Add to ~/.config/opencode/opencode.json (or opencode.jsonc):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "local-rag": {
      "type": "local",
      "command": ["npx", "-y", "mcp-local-rag"],
      "environment": {
        "BASE_DIR": "/absolute/path/to/your/documents"
      }
    }
  }
}

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "local-rag": {
      "command": "npx",
      "args": ["-y", "mcp-local-rag"],
      "env": {
        "BASE_DIR": "/absolute/path/to/your/documents"
      }
    }
  }
}

The MCP server reads environment variables. The CLI accepts the listed variables and flags. Keep the same DB_PATH when commands should use the same index.

File operations stay within configured roots. For multiple directories, set BASE_DIRS='["/absolute/docs","/absolute/specs"]' or repeat CLI --base-dir. Precedence: CLI roots, BASE_DIRS, BASE_DIR, then the current directory. Only the highest-priority source is used; roots from different sources are not merged. Invalid BASE_DIRS is an error. Relative DB_PATH and CACHE_DIR are resolved from the working directory.

Choose an embedding model for your documents’ language and subject. Compare settings using questions you actually ask and check which source passages are returned. The model must support mean pooling and L2 normalization, which this tool uses to produce embeddings.

Both prefix options default to false and work independently. Try EMBED_TITLE_PREFIX when a passage needs the document’s overall topic, or EMBED_HEADING_PREFIX when it needs its section’s topic. Enabling both is not always better. They affect embeddings, not the returned text or keyword index; heading context is omitted when it would exceed the input budget.

When changing embedding models, build a fresh index at a new DB_PATH. Vectors from different models are not comparable, even when their dimensions match. After changing RAG_DTYPE or either prefix option, re-ingest all indexed documents before searching. sync skips unchanged files.

The CLI does not read MCP client configuration. When sharing an index, use the same model, RAG_DTYPE, and prefix settings for ingestion and search. A change to RAG_DEVICE alone does not require a new index.

Search Tuning

The first four settings below apply to both MCP and CLI queries. To give exact terms more weight, try increasing RAG_HYBRID_WEIGHT and compare results on your own questions. External reranking is MCP-only.

External Reranking (RAG_RERANK_CMD)

The command reads search results, including matched text, from stdin. If it calls a remote service, that text may leave your machine.

Give the executable and its complete argument template. Put {query} and {top} where the command expects the query and result count. Single or double quotes group paths or arguments containing spaces, and backslashes stay literal. The server runs the executable without a shell, so an npm-installed .cmd shim on Windows will not start.

{
  "env": {
    "RAG_RERANK_CMD": "/path/to/reranker --query {query} --top {top}",
    "RAG_RERANK_TIMEOUT_MS": "10000"
  }
}

The command must read and return results in the format defined by the query output schema. It can remove or reorder results and modify their text. The server returns its output.

Results keep their original order if the command fails, times out, or returns output that does not match the schema.

By default, ingestion indexes only text. To make PDF figures searchable, enable local caption generation with visual: true in MCP or --visual in the CLI. Captions are generated descriptions, not OCR or exact transcriptions.

fast (default) downloads about 250 MB on first use. Choose quality for labels and text within figures; it downloads about 1.7 GB and takes longer to run.

Select the profile with visualQuality: "quality" in MCP or --visual-quality quality in the CLI.

npx mcp-local-rag ingest ./docs/paper.pdf --visual --visual-quality quality

To return images with matching text, use STORE_IMAGES=true in MCP or --images with CLI ingest and sync. This is independent of caption generation and supports detected PDF figures/tables and supported DOCX PNG/JPEG images.

npx mcp-local-rag ingest ./docs/paper.pdf --images

Sync preserves each PDF's caption profile. CLI sync --visual --visual-quality quality changes the profile even for unchanged PDFs; MCP sync preserves it. To turn captions off, ingest the file normally. To retry failed captions, re-ingest with the desired visual profile.

Image storage must be enabled on each ingestion or sync that processes the file. Changing the image setting alone does not refresh unchanged files; re-ingest them to apply it.

"No results found"

Documents must be ingested first. Run "List all ingested files" to verify. If results are missing after a sync, check that ingestion and search use the same absolute DB_PATH; a relative path may point to a different index.

Model download failed

Check internet connection. If behind a proxy, configure network settings. The model can also be downloaded manually.

"File too large"

Default limit is 100MB. Split large files or increase MAX_FILE_SIZE.

Slow queries

Check chunk count with status. Large documents with many chunks may slow queries. Consider splitting very large files.

"Path outside BASE_DIR"

Ensure file paths are within one of the configured roots (BASE_DIR, any BASE_DIRS entry, or any CLI --base-dir). Use absolute paths.

"BASE_DIRS must be a JSON array..."

BASE_DIRS accepts a JSON array of one or more non-empty path strings:

• Valid: BASE_DIRS='["/Users/me/work","/Users/me/specs"]'
• Invalid: BASE_DIRS=/a:/b (delimiter syntax not supported)
• Invalid: BASE_DIRS='[]' (empty array)

MCP client doesn't see tools

1. Verify config file syntax
2. Restart client completely (Cmd+Q on Mac for Cursor)
3. Test directly: npx mcp-local-rag should run without errors