Locus

Your files, your machine, the MCP clients you already use.

Locus indexes folders you choose on your own computer and gives MCP clients that can start a local server (tested: Claude Desktop, Claude Code and Cursor) a semantic search tool over them. Every result carries the file path, so the assistant can cite its sources.

The package is locusfiles; the command it installs is locus.

Install

You need Python 3.11 or newer. Install with pipx or uv, which put locus in its own environment. These commands work once locusfiles is published on PyPI (first upload planned for 2026-10-01):

# On-device embeddings, no account (downloads PyTorch, about 1-2 GB):
pipx install "locusfiles[local]"
# or
uv tool install --python 3.12 "locusfiles[local]"

# A Locus plan (managed embeddings, remote connection), no PyTorch:
pipx install "locusfiles[relay]"

Other extras: voyage or openai to embed with your own provider key.

macOS and Linux are tested. Windows is not yet verified.

First search

export LOCUS_EMBEDDER=local            # or managed (with LOCUS_API_KEY), voyage, openai
locus doctor                           # checks Python, packages, settings and the embedder
locus index ~/Documents/notes --prune  # parse, chunk, embed and index a folder
locus query "what did I decide about pricing" -k 5

Then connect your AI assistant: it runs locus serve (MCP over stdio). Setup steps for each client are on the Locus website's Connect page (/docs/connect).

What leaves your computer

• Local: Indexing and embeddings run on your computer. When your AI assistant searches, the matching excerpts go to that assistant, as they would if you pasted them in.
• Your own key: Chunk text goes straight from your computer to the embedding provider you chose, under your own account.
• Managed: On managed plans, chunk text passes through Locus's relay to Voyage AI to be embedded. We don't store it; we keep only usage counts.
• Remote: When you reach your computer from another device or a web AI app, your question and the matching excerpts travel through Locus's relay (Vercel and Supabase) to and from your computer. They are encrypted in transit and we don't store them.
• In every mode: Your raw files are never uploaded to Locus.

Indexes live in ~/.locus (set LOCUS_DATA_DIR to move them). Settings are environment variables, or a .env file in the directory you run locus from or one of its parents.