localrag

Zero-dependency local semantic search over your own files — plus a tiny MCP server so Claude (or any MCP client) can search them as a tool.

• Nothing leaves your machine. Embeddings come from any OpenAI-compatible endpoint; point it at Ollama, LM Studio, llama.cpp, or vLLM running locally.
• No dependencies. Pure standard library — urllib, json, math. The index is one JSON file; search is plain cosine similarity.
• Two ways in: a localrag CLI, and an MCP server (search_docs tool).

Install

pip install localrag

Quick start

Assuming Ollama with an embedding model:

ollama pull nomic-embed-text

localrag build ~/notes ~/docs        # index your files (.md/.txt/.rst)
localrag query "what did I decide about the deploy pipeline?"
localrag query "deploy pipeline" --answer   # retrieve + let a chat model answer

Output:

=== top 5 for: deploy pipeline ===

[1] (0.812) notes/ops.md
    We settled on blue/green with a manual approval gate before cutover...

Use it from Claude / any MCP client (the search_docs tool)

Run the server:

python -m localrag.mcp_server

Register it with an MCP client. For Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "localrag": {
      "command": "python",
      "args": ["-m", "localrag.mcp_server"],
      "env": { "LOCALRAG_INDEX": "/home/you/notes/localrag-index.json" }
    }
  }
}

Now the model can call search_docs("...") to ground its answers in your notes.

Configuration

All optional — sensible local defaults out of the box.

Env var	Meaning	Default
LOCALRAG_EMBED_URL	OpenAI-compatible base URL (incl. /v1)	http://localhost:11434/v1
LOCALRAG_EMBED_MODEL	embedding model	nomic-embed-text
LOCALRAG_CHAT_URL	base URL for --answer	= LOCALRAG_EMBED_URL
LOCALRAG_CHAT_MODEL	chat model for --answer	qwen3
LOCALRAG_API_KEY	bearer token, if your server needs one	(none)
LOCALRAG_INDEX	index file path	./localrag-index.json

Using a hosted endpoint instead of local? Point LOCALRAG_EMBED_URL at it and set LOCALRAG_API_KEY — the same code path works with the OpenAI API.

How it works

1. Chunk — files are split on blank lines into ~800-char blocks with a small overlap so context isn't cut mid-thought.
2. Embed — each chunk is embedded once and stored with its vector in a JSON index.
3. Search — the query is embedded and ranked against every chunk by cosine similarity. For --answer, the top chunks become the sole context for a grounded reply.

Small corpora (thousands of chunks) are the sweet spot: no database, no server, just a file you can commit or delete.

License

MIT — see LICENSE.