Gnosis MCP — Claude Code MCP server: search your local docs
Builds a local index over your project docs and hands the agent ranked snippets instead of whole files. Useful when context keeps filling up with READMEs.
claude mcp add gnosis -- uvx gnosis-mcpWhat Gnosis MCP does
Gnosis MCP ingests markdown, .txt, .ipynb, .toml, .csv and .json files, plus git commit history and pages crawled from a site via sitemap. Retrieval mixes BM25 keyword matching with semantic search over local ONNX embeddings, so no API key is involved. Setup is three commands: pip install gnosis-mcp, then gnosis-mcp ingest ./docs/, then gnosis-mcp serve. The SQLite database is created on its own.
The pitch is token math. A search_docs call comes back with 200–500 tokens of highlighted excerpts where a full-file read would have cost 3000–15000. Watch mode re-ingests on file changes, --prune drops chunks whose source file is gone, --wipe resets before a fresh ingest, and gnosis-mcp savings tallies what you avoided. PostgreSQL with pgvector and tsvector is there for larger corpora.
Think twice before turning on cross-encoder reranking. The bundled MS-MARCO model costs 27 points of nDCG@10 on dev docs and adds 400× latency in the author's measurements, which is why it ships off. Test it against your own corpus first. And gnosis-mcp eval is a smoke test — nine hardcoded documents, ten bundled queries — not a score for your docs; use python tests/bench/bench_real_corpus.py --corpus <docs-root> --golden <golden.jsonl> for that.
What it helps with
- find the right section of docs without reading ten files
- cut token spend on repeated lookups against the same docs
- feed commit history to the agent as searchable context
- index a documentation site from its sitemap
- drop chunks of deleted files from the index
Example prompts for the agent
- Search my local docs for how OAuth login is configured
- Ingest the
./docs/folder and show me corpus stats - How many tokens did doc lookups save over the last 7 days?
How to install Gnosis MCP
Platform CLI
claude mcp add gnosis -- uvx gnosis-mcpuvx runs the command named after the package; if the README names another one, use uvx --from gnosis-mcp <command>
Platform CLI
codex mcp add gnosis-mcp -- uvx gnosis-mcpuvx runs the command named after the package; if the README names another one, use uvx --from gnosis-mcp <command>
Config file
{
"mcpServers": {
"gnosis-mcp": {
"command": "uvx",
"args": [
"gnosis-mcp"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from gnosis-mcp <command>
Config file
{
"servers": {
"gnosis-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"gnosis-mcp"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from gnosis-mcp <command>
Platform CLI
gemini mcp add gnosis-mcp uvx gnosis-mcpuvx runs the command named after the package; if the README names another one, use uvx --from gnosis-mcp <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Gnosis MCP
How do I install Gnosis MCP in Claude Code?
Run claude mcp add gnosis -- uvx gnosis-mcp. The server is then available to the agent, and you can load docs with gnosis-mcp ingest ./docs/.
What does Gnosis MCP do?
It builds a local search index over your documentation and returns ranked, highlighted excerpts to the agent. Nothing leaves the host.
Does it need an API key or a cloud service?
No. Semantic search runs on local ONNX embeddings and SQLite is the default store. PostgreSQL with pgvector is for when you need scale.
