Cursor — Global: ~/.cursor/mcp.json, Project: .cursor/mcp.json

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

Codex — ~/.codex/config.toml (note: must use mcp_servers with underscore)

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

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

Claude Code:

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

The embedding model (~90MB) downloads on first use. Takes 1-2 minutes, then works offline.

• Path restriction: Only files within BASE_DIR are accessible
• Local only: No network requests after model download
• Model source: Official HuggingFace repository (verify here)

Tested on MacBook Pro M1 (16GB RAM), Node.js 22:

Query Speed: ~1.2 seconds for 10,000 chunks (p90 < 3s)

Ingestion (10MB PDF):

• PDF parsing: ~8s
• Chunking: ~2s
• Embedding: ~30s
• DB insertion: ~5s

Memory: ~200MB idle, ~800MB peak (50MB file ingestion)

Concurrency: Handles 5 parallel queries without degradation.

Documents must be ingested first. Run "List all ingested files" to verify.

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

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

Check chunk count with status. Consider increasing CHUNK_SIZE to reduce the number of chunks (trade-off: larger chunks may reduce retrieval precision).

Ensure file paths are within BASE_DIR. Use absolute paths.

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

Is this really private? Yes. After model download, nothing leaves your machine. Verify with network monitoring.

Can I use this offline? Yes, after the first model download (~90MB).

How does this compare to cloud RAG? Cloud services offer better accuracy at scale but require sending data externally. This trades some accuracy for complete privacy and zero runtime cost.

What file formats are supported? PDF, DOCX, TXT, Markdown. Not yet: Excel, PowerPoint, images, HTML.

Can I change the embedding model? Yes, but you must delete your database and re-ingest all documents. Different models produce incompatible vector dimensions.

GPU acceleration? Transformers.js runs on CPU. GPU support is experimental. CPU performance is adequate for most use cases.

Multi-user support? No. Designed for single-user, local access. Multi-user would require authentication/access control.

How to backup? Copy DB_PATH directory (default: ./lancedb/).

git clone https://github.com/shinpr/mcp-local-rag.git
cd mcp-local-rag
npm install

npm test              # Run all tests
npm run test:coverage # With coverage
npm run test:watch    # Watch mode

npm run type-check    # TypeScript check
npm run check:fix     # Lint and format
npm run check:deps    # Circular dependency check
npm run check:all     # Full quality check

src/
  index.ts      # Entry point
  server/       # MCP tool handlers
  parser/       # PDF, DOCX, TXT, MD parsing
  chunker/      # Text splitting
  embedder/     # Transformers.js embeddings
  vectordb/     # LanceDB operations
  __tests__/    # Test suites

Each module has clear boundaries:

• Parser validates file paths and extracts text
• Chunker splits text into overlapping segments
• Embedder generates 384-dimensional vectors
• VectorStore handles all database operations
• RAGServer orchestrates everything and exposes MCP tools

Test Environment: MacBook Pro M1 (16GB RAM), tested with v0.1.3 on Node.js 22 (January 2025)

Query Performance:

• Average: 1.2 seconds for 10,000 indexed chunks (5 results)
• Target: p90 < 3 seconds ✓

Ingestion Speed (10MB PDF):

• Total: ~45 seconds
  • PDF parsing: ~8 seconds (17%)
  • Text chunking: ~2 seconds (4%)
  • Embedding generation: ~30 seconds (67%)
  • Database insertion: ~5 seconds (11%)

Memory Usage:

• Baseline: ~200MB idle
• Peak: ~800MB when ingesting 50MB file
• Target: < 1GB ✓

Concurrent Queries: Handles 5 parallel queries without degradation. LanceDB's async API allows non-blocking operations.

Note: Your results will vary based on hardware, especially CPU speed (embeddings run on CPU, not GPU).

Cause: Documents must be ingested before searching.

Solution:

1. First ingest documents: "Ingest /path/to/document.pdf"
2. Verify ingestion: "List all ingested files"
3. Then search: "Search for [your query]"

Common mistake: Trying to search immediately after configuration without ingesting any documents.

The embedding model downloads from HuggingFace on first use (when you ingest or search for the first time). If you're behind a proxy or firewall, you might need to configure network settings.

When it happens: Your first ingest or search operation will trigger the download. If it fails, you'll see a detailed error message with troubleshooting guidance (network issues, disk space, cache corruption).

What to do: The error message provides specific recommendations. Common solutions:

1. Check your internet connection and retry the operation
2. Ensure you have sufficient disk space (~120MB needed)
3. If problems persist, delete the cache directory and try again

Alternatively, download the model manually:

1. Visit https://huggingface.co/Xenova/all-MiniLM-L6-v2
2. Download the model files
3. Set CACHE_DIR to where you saved them

Default limit is 100MB. For larger files:

• Split them into smaller documents
• Or increase MAX_FILE_SIZE in your config (be aware of memory usage)

If queries take longer than expected:

• Check how many chunks you have indexed (status command)
• Consider the hardware (embeddings are CPU-intensive)
• Try reducing CHUNK_SIZE to create fewer chunks

The server restricts file access to BASE_DIR for security. Make sure your file path is within that directory. Check for:

• Correct BASE_DIR setting in your MCP config
• Relative paths vs absolute paths
• Typos in the file path

For Cursor:

1. Open Settings → Features → Model Context Protocol
2. Verify the server configuration is saved
3. Restart Cursor completely
4. Check the MCP connection status in the status bar

For Codex CLI:

1. Check ~/.codex/config.toml to verify the configuration
2. Ensure the section name is [mcp_servers.local-rag] (with underscore)
3. Test the server directly: npx mcp-local-rag should run without errors
4. Restart Codex CLI or IDE extension
5. Check for error messages when Codex starts

For Claude Code:

1. Run claude mcp list to see configured servers
2. Verify the server appears in the list
3. Check ~/.config/claude/mcp_config.json for syntax errors
4. Test the server directly: npx mcp-local-rag should run without errors

Common issues:

• Invalid JSON syntax in config files
• Wrong file paths in BASE_DIR setting
• Server binary not found (try global install: npm install -g mcp-local-rag)
• Firewall blocking local communication

When you ingest a document, the parser extracts text based on the file type. PDFs use pdf-parse, DOCX uses mammoth, and text files are read directly.

The chunker then splits the text using LangChain's RecursiveCharacterTextSplitter. It tries to break on natural boundaries (paragraphs, sentences) while keeping chunks around 512 characters. Adjacent chunks overlap by 100 characters to preserve context.

Each chunk goes through the Transformers.js embedding model, which converts text into a 384-dimensional vector representing its semantic meaning. This happens in batches of 8 chunks at a time for efficiency.

Vectors are stored in LanceDB, a columnar vector database that works with local files. No server process, no complex setup. It's just a directory with data files.

When you search, your query becomes a vector using the same model. LanceDB finds the chunks with vectors most similar to your query vector (using cosine similarity). The top matches return to your MCP client with their original text and metadata.

The beauty of this approach: semantically similar text has similar vectors, even if the words are different. "authentication process" and "how users log in" will match each other, unlike keyword search.

Is this really private?

Yes. After the initial model download, nothing leaves your machine. You can verify with network monitoring tools—no outbound requests during ingestion or search.

Can I use this offline?

Yes, once the model is cached. The first run needs internet to download the model (~90MB), but after that, everything works offline.

How does this compare to cloud RAG services?

Cloud services (OpenAI, Pinecone, etc.) typically offer better accuracy and scale. But they require sending your documents externally, ongoing costs, and internet connectivity. This project trades some accuracy for complete privacy and zero runtime cost.

What file formats are supported?

Currently supported:

• PDF: .pdf (uses pdf-parse)
• Microsoft Word: .docx (uses mammoth, not .doc)
• Plain Text: .txt
• Markdown: .md, .markdown
• Code Files:
  • TypeScript: .ts, .tsx
  • JavaScript: .js, .jsx
  • Python: .py
  • Java: .java
  • Go: .go
  • Rust: .rs
  • C/C++: .c, .cpp, .cc, .cxx, .h, .hpp
  • Ruby: .rb
  • PHP: .php
  • C#: .cs
  • Shell: .sh
  • SQL: .sql
• Text Snippets: Direct text ingestion via memorize_text tool (no file needed)

Not yet supported:

• Excel/CSV (.xlsx, .csv)
• PowerPoint (.pptx)
• Images with OCR (.jpg, .png)
• HTML (.html)
• Old Word documents (.doc)

Want support for another format? Open an issue with your use case.

Can I customize the embedding model?

Yes, set MODEL_NAME to any Transformers.js-compatible model from HuggingFace. Keep in mind that different models have different vector dimensions, so you'll need to rebuild your database if you switch.

How much does accuracy depend on the model?

all-MiniLM-L6-v2 is optimized for English and performs well for technical documentation. For other languages, consider multilingual models like multilingual-e5-small. For higher accuracy, try larger models—but expect slower processing.

What about GPU acceleration?

Transformers.js runs on CPU by default. GPU support is experimental and varies by platform. For most use cases, CPU performance is adequate (embeddings are reasonably fast even without GPU).

Can multiple people share a database?

The current design assumes single-user, local access. For multi-user scenarios, you'd need to implement authentication and access control—both out of scope for this project's privacy-first design.

How do I back up my data?

Copy your DB_PATH directory (default: ./lancedb/). That's your entire vector database. Copy BASE_DIR for your original documents. Both are just files—no special export needed.

Contributions welcome. Before submitting a PR:

1. Run tests: npm test
2. Check quality: npm run check:all
3. Add tests for new features
4. Update docs if behavior changes

MIT License. Free for personal and commercial use.

Built with Model Context Protocol by Anthropic, LanceDB, Transformers.js, and LangChain.js.