A local-first MCP server for safe, scoped codebase access and hybrid search.
LocalNest MCP
Your codebase. Your AI. Your machine — no cloud, no leaks, no surprises.
LocalNest is a local-first MCP server that gives AI agents safe, scoped access to your code — with hybrid search, semantic indexing, and persistent memory that never leaves your machine.
📖 Full documentation · Architecture deep dive
Why LocalNest?
Most AI code tools phone home. LocalNest doesn't.
Everything — file reads, vector embeddings, memory — runs in-process on your machine. No cloud subscription, no rate limits, no data leaving your box. And because it speaks MCP, any compatible client (Cursor, Windsurf, Codex, Kiro, Gemini CLI) can plug in with one config block.
| What you get | How it works |
|---|---|
| Safe file access | Scoped reads under your configured roots — nothing outside |
| Instant lexical search | ripgrep-backed symbol and pattern search (JS fallback if missing) |
| Semantic search | Local vector embeddings via all-MiniLM-L6-v2 — no GPU needed |
| Hybrid retrieval | Lexical + semantic fused with RRF ranking for best-of-both results |
| Project awareness | Auto-detects projects from marker files, scopes every tool call |
| Agent memory | Durable, queryable knowledge graph — your AI remembers what it learned |
Quick Start
npm install -g localnest-mcp
localnest setup
localnest doctor
3. Drop this into your MCP client config
Setup auto-writes the config for detected tools. You'll also find a ready-to-paste block at ~/.localnest/config/mcp.localnest.json:
{
"mcpServers": {
"localnest": {
"command": "localnest-mcp",
"startup_timeout_sec": 30,
"env": {
"MCP_MODE": "stdio",
"LOCALNEST_CONFIG": "~/.localnest/config/localnest.config.json",
"LOCALNEST_INDEX_BACKEND": "sqlite-vec",
"LOCALNEST_DB_PATH": "~/.localnest/data/localnest.db",
"LOCALNEST_INDEX_PATH": "~/.localnest/data/localnest.index.json",
"LOCALNEST_EMBED_PROVIDER": "huggingface",
"LOCALNEST_EMBED_MODEL": "sentence-transformers/all-MiniLM-L6-v2",
"LOCALNEST_EMBED_CACHE_DIR": "~/.localnest/cache",
"LOCALNEST_EMBED_DIMS": "384",
"LOCALNEST_RERANKER_PROVIDER": "huggingface",
"LOCALNEST_RERANKER_MODEL": "cross-encoder/ms-marco-MiniLM-L-6-v2",
"LOCALNEST_RERANKER_CACHE_DIR": "~/.localnest/cache",
"LOCALNEST_MEMORY_ENABLED": "false",
"LOCALNEST_MEMORY_BACKEND": "auto",
"LOCALNEST_MEMORY_DB_PATH": "~/.localnest/data/localnest.memory.db"
}
}
}
}
Windows: Use the config written by
localnest setup— it sets the correct command for your platform automatically.
Restart your MCP client. If it times out, set startup_timeout_sec: 30 in your client config.
Requirements: Node.js >=18 · ripgrep recommended but optional
AST-aware chunking ships by default for JavaScript, Python, Go, Bash, Lua, and Dart. Other languages still index cleanly with line-based fallback chunking.
The current stable runtime uses @huggingface/transformers for local embeddings and reranking. New setup defaults use huggingface, and older xenova configs remain accepted as a compatibility alias.
# macOS
brew install ripgrep
# Ubuntu/Debian
sudo apt-get install ripgrep
# Windows
winget install BurntSushi.ripgrep.MSVC
Upgrade
localnest upgrade # latest stable
localnest upgrade stable # latest stable
localnest upgrade beta # latest beta
localnest upgrade <version> # pin to a specific version
localnest version # check current
How Agents Use It
Two workflows cover almost everything:
Fast lookup — find it, read it, done
Best for pinpointing a file, symbol, or code pattern.
localnest_search_files → fi
Tools (1)
localnest_search_filesPerforms a search across the codebase to find files, symbols, or patterns.Environment Variables
LOCALNEST_CONFIGPath to the localnest configuration fileLOCALNEST_INDEX_BACKENDBackend engine for indexingLOCALNEST_EMBED_PROVIDERProvider for vector embeddingsLOCALNEST_MEMORY_ENABLEDToggle for persistent agent memoryConfiguration
{"mcpServers": {"localnest": {"command": "localnest-mcp", "startup_timeout_sec": 30, "env": {"MCP_MODE": "stdio", "LOCALNEST_CONFIG": "~/.localnest/config/localnest.config.json", "LOCALNEST_INDEX_BACKEND": "sqlite-vec", "LOCALNEST_DB_PATH": "~/.localnest/data/localnest.db", "LOCALNEST_INDEX_PATH": "~/.localnest/data/localnest.index.json", "LOCALNEST_EMBED_PROVIDER": "huggingface", "LOCALNEST_EMBED_MODEL": "sentence-transformers/all-MiniLM-L6-v2", "LOCALNEST_EMBED_CACHE_DIR": "~/.localnest/cache", "LOCALNEST_EMBED_DIMS": "384", "LOCALNEST_RERANKER_PROVIDER": "huggingface", "LOCALNEST_RERANKER_MODEL": "cross-encoder/ms-marco-MiniLM-L-6-v2", "LOCALNEST_RERANKER_CACHE_DIR": "~/.localnest/cache", "LOCALNEST_MEMORY_ENABLED": "false", "LOCALNEST_MEMORY_BACKEND": "auto", "LOCALNEST_MEMORY_DB_PATH": "~/.localnest/data/localnest.memory.db"}}}}