gnosis-mcp
docs · graph · meta
meta

Gnosis MCP — Installation Guide

llms-install.md

Gnosis MCP — Installation Guide

Three install paths, pick the one that matches how you work:

You want… Path Effort
Plugin for Claude Code — agents, skills, hooks, and the MCP server auto-wired Path A (plugin marketplace) One command
Manual control — cherry-pick which agents/skills land in your config, edit them first Path B (copy-paste) ~5 minutes
Just the MCP server — you don't use Claude Code or don't want the plugin extras Path C (MCP-only) Per-editor JSON snippet

All three paths install the same underlying gnosis-mcp Python package. The difference is what wires up around it.

Agent checklist

For an AI agent installing gnosis-mcp on a user's behalf. Work these in order — each step says how to verify it and what to do when it fails. The prose below is the same procedure written for humans; Path C is the closest match.

  1. Confirm the target. Ask which folder of docs to index, and whether the user wants the Claude Code extras (Path A or Path B) or only the MCP server (Path C). Don't guess the docs path.

  2. Install. Python 3.11 or later (python --version).

    pip install 'gnosis-mcp[embeddings,web]'
# or, when the machine has no suitable Python:
uv tool install 'gnosis-mcp[embeddings,web]'

    Verify: gnosis-mcp --version prints a version. If it fails: no Python 3.11+ — install uv and use the uv tool install form; on Windows see Platforms for the .exe path.

  3. Check that SQLite has FTS5 — before ingesting. Keyword search needs SQLite FTS5, which is compiled into the Python build rather than guaranteed by it. Run this with the same Python that runs gnosis-mcp:

    python -c "import sqlite3; sqlite3.connect(':memory:').execute('CREATE VIRTUAL TABLE t USING fts5(x)')"

    Exit 0 = FTS5 is present. no such module: fts5 = it is not — stop and tell the user, because every later step would appear to succeed while search returns nothing. Fix the Python (python.org installer, uv python install) or use PostgreSQL instead.

  4. Initialise the database. gnosis-mcp init-db (idempotent). Verify: gnosis-mcp check prints FTS5: ready and ends with Result: healthy (exit 0) — the exit code is the gate. A non-zero exit here is a stop condition, not a warning.

  5. Ingest. gnosis-mcp ingest <path> --dry-run to preview, then gnosis-mcp ingest <path> --embed. Verify: gnosis-mcp stats reports a non-zero Documents / Chunks count.

  6. Prove retrieval works. gnosis-mcp search "<a phrase you know is in the docs>" must return hits. If it returns nothing, the user's agent will find nothing either — fix that before wiring a client.

  7. Wire the client. Run gnosis-mcp setup to see what it wants to write, then gnosis-mcp setup --write to apply it. This is not a convenience wrapper — it is the only path that resolves the server command for this machine, which is the step every hand-copied snippet gets wrong. --client <name> limits it to one client, --json gives you a machine-readable report. See Wire the client for the full surface and for the clients whose config is not a JSON map (Platforms covers Windows).

  8. Prove it gets used. Run gnosis-mcp doctor. A config file only expresses intent; the doctor reads the access log and tells you whether a client has actually called the server. "Wired but no call has ever been logged" is the failure this catches, and it is invisible everywhere else — no error, no log line, no results.

  9. Report. Docs path, database path, backend, doc/chunk counts, the client config file you wrote, and anything you skipped. If a step failed, report the failure instead of continuing or claiming success.

Failures at any step: docs/troubleshooting.md. Never report "setup complete" without the check, search and doctor output to back it.

Wire the client

Installing the package is half an installation. The other half is a client that knows where the binary is, and an agent that chooses to call it. setup does the first, doctor checks both.

gnosis-mcp setup                    # preview: what would be written, and where
gnosis-mcp setup --write            # apply, for every client detected on this machine
gnosis-mcp setup --client dsh --write
gnosis-mcp setup --list             # every client it knows about
gnosis-mcp doctor                   # is it wired, and has anything actually called it?

setup never writes without --write, and each block it installs is delimited by markers naming the command that regenerates it — so re-running after an upgrade updates one region in place instead of appending a second copy. Everything outside those markers is left byte-for-byte alone.

Two things it does that a pasted snippet cannot:

  • It resolves the command for the machine you are on. gnosis-mcp is rarely where the README assumed: uv tool install puts a symlink in ~/.local/bin, a venv install is only reachable through its own bin, and a client spawns servers from a different working directory and a different PATH than your shell. setup writes the stable absolute path that exists here.
  • It writes the rule that makes the agent use it. A mounted server whose tools the agent never prefers is the common, silent outcome. Where a client does not forward the server's own MCP instructions field, setup also writes a short rule into that client's always-loaded instruction file, so "search gnosis first" is part of the session rather than a hope.
Client Config it writes Instruction file
Claude Code ~/.claude.json (via claude mcp add-json when available) — reads MCP instructions
DeepSeek Harness $DSH_HOME/profiles/<profile>/cordis.patch.yml $DSH_HOME/AGENTS.md
OpenAI Codex CLI ~/.codex/config.toml (via codex mcp add when available) ~/.codex/AGENTS.md
Gemini CLI ~/.gemini/settings.json ~/.gemini/GEMINI.md
Cursor ~/.cursor/mcp.json .cursor/rules/gnosis.mdc
VS Code (Copilot) <user>/Code/User/mcp.json — key is servers, not mcpServers —
Windsurf ~/.codeium/windsurf/mcp_config.json —
Cline VS Code global storage cline_mcp_settings.json —
Zed ~/.config/zed/settings.json — context_servers, nested command; printed, not written —
anything else printed as a stdio entry (gnosis-mcp setup --client generic) —

Where a client ships its own mcp add command, setup runs it and does not touch the file itself: their schema, their validation, their version. If that command exists but fails, setup reports the failure instead of quietly writing a second config the vendor's tooling would disagree with. --no-cli forces direct file edits.

The DeepSeek Harness row goes in the profile patch layer, not an agent preset, so every session on every preset gets the tools. That layer reloads live — no restart needed after setup --write. doctor additionally runs dsh --dump-config and reports whether the harness still accepts the composed profile, which is the only check that catches a row the loader rejects.

Any other MCP client

Claude Code is not required. Any MCP client works — install the package, index your docs, then let setup figure out the entry:

pip install gnosis-mcp
gnosis-mcp ingest ./docs/
gnosis-mcp setup --client generic     # prints the entry, with the right absolute path

{
  "mcpServers": {
    "gnosis": {
      "command": "/home/you/.local/bin/gnosis-mcp",
      "args": ["serve"]
    }
  }
}

Add --write and a --client <name> from the table above to install it directly. Config file locations for the clients that are not in that table are in Path C below.

Prerequisites

  • Python 3.11 or later
  • A folder of markdown files you want your AI agent to search

No database server required — SQLite works out of the box.

Platforms

Platform Install Database Notes
Linux / macOS pip install 'gnosis-mcp[embeddings,web]', or uv tool install ~/.local/share/gnosis-mcp/docs.db Docker, systemd and the reverse-proxy recipes in docs/deployment.md assume Linux.
Windows (native) winget install astral-sh.uv, then uv tool install 'gnosis-mcp[embeddings,web]' — plain pip install works too %USERPROFILE%\.local\share\gnosis-mcp\docs.db Before ingesting, run the FTS5 probe from step 3 of the checklist: keyword search needs SQLite FTS5, which is compiled into the Python build rather than guaranteed by it. pip/uv install console scripts as .exe shims under %USERPROFILE%\.local\bin, so point your MCP client at the full path to gnosis-mcp.exe instead of relying on PATH inheritance.
Windows via WSL2 Same as Linux, inside WSL Inside the WSL filesystem The simplest route to Docker or systemd from Windows — localhost forwarding means a Windows client reaches http://127.0.0.1:8000/mcp. Index docs that live in the Linux filesystem.
Remote server / VM Same as Linux, on the host On the host Serve over HTTP and connect to the host's address (below). Set GNOSIS_MCP_API_KEY whenever the network is not trusted.

Windows: worked MCP server entry

Stdio, with the full path to the .exe (backslashes doubled for JSON):

{
  "mcpServers": {
    "gnosis": {
      "command": "C:\\Users\\you\\.local\\bin\\gnosis-mcp.exe",
      "args": ["serve"]
    }
  }
}

Remote / WSL / VM: HTTP transport

Start the server on the machine that holds the database:

gnosis-mcp serve --transport streamable-http --host 0.0.0.0 --port 8000

Then point the client at it — 127.0.0.1 from a Windows client under WSL2 (localhost forwarding), or the host's address from anywhere else:

{
  "mcpServers": {
    "gnosis": {
      "type": "url",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Set GNOSIS_MCP_API_KEY on the server for any non-loopback exposure — see the security checklist in docs/deployment.md.

Path A — Claude Code plugin (recommended)

If you use Claude Code, this is the one-command install. Gets you the MCP server plus 5 subagents, 8 slash commands, and a session-start health check.

# Install the Python package first
pip install 'gnosis-mcp[embeddings,web]'

# Tell Claude Code about this marketplace, then install the plugin
claude plugin marketplace add nicholasglazer/gnosis-mcp
claude plugin install gnosis

# Index your docs
gnosis-mcp ingest ./docs/ --embed

Restart Claude Code. You now have:

Component What you get
MCP server gnosis-mcp serve — auto-configured, search tools available in every chat
/gnosis:setup First-time wizard: install → init-db → ingest → wire your editor
/gnosis:ingest Bulk ingest (files, git history, web crawl) + re-ingest + prune
/gnosis:search Keyword / hybrid / git-history search, formatted output
/gnosis:manage Single-file CRUD (add, delete, update metadata, related)
/gnosis:tune Chunk-size sweep against your own golden queries
/gnosis:eval Single-shot retrieval quality check with baseline tracking
/gnosis:context Usage-weighted topic primer for session startup
/gnosis:status Connectivity, schema, corpus health diagnostic
5 agents doc-explorer, doc-keeper, corpus-sync, context-loader, doc-reviewer
Session hook Checks DB connectivity on session start — warns loudly if unreachable

Path B — Manual copy-paste

For users who want to pick specific agents/skills, edit them before installing, or use a non-plugin-capable MCP client.

# 1. Clone the repo to grab the agents + skills
git clone https://github.com/nicholasglazer/gnosis-mcp /tmp/gnosis-mcp

# 2. Install the Python package
pip install 'gnosis-mcp[embeddings,web]'

# 3. Copy whichever agents + skills you want into your project
mkdir -p .claude/agents .claude/skills
cp /tmp/gnosis-mcp/agents/*.md .claude/agents/           # all 5 — or pick specific ones
cp -r /tmp/gnosis-mcp/skills/* .claude/skills/           # all 8 — or pick specific dirs

# 4. Wire gnosis-mcp as an MCP server
cat > .mcp.json <<'JSON'
{
  "mcpServers": {
    "gnosis": {
      "command": "gnosis-mcp",
      "args": ["serve"]
    }
  }
}
JSON

# 5. Index your docs
gnosis-mcp ingest ./docs --embed

Restart your Claude Code session. The agents and slash commands are available exactly as with Path A, just with whichever subset you chose to copy. Edit the .md files to customize prompts for your codebase before (or after) copying.

To remove later: rm .claude/agents/<name>.md or rm -rf .claude/skills/<name>/.

Path C — MCP server only (any editor)

If you don't use Claude Code, don't want the agent/skill bundle, or want to wire gnosis-mcp as a plain MCP server in a different editor.

Step 1: Install

pip install gnosis-mcp

Or with uvx (no install needed):

uvx gnosis-mcp serve

For local semantic search (no API key needed, ~23MB model download):

pip install gnosis-mcp[embeddings]

For PostgreSQL support:

pip install gnosis-mcp[postgres]

For web crawling (ingest docs from websites):

pip install gnosis-mcp[web]

Step 2: Load Your Docs

Point at a folder of markdown files:

gnosis-mcp ingest ./docs/

This auto-creates the SQLite database at ~/.local/share/gnosis-mcp/docs.db (Unix/macOS) or %USERPROFILE%\.local\share\gnosis-mcp\docs.db (Windows), scans all .md files, chunks them by H2 headings, extracts metadata from frontmatter, and inserts into the database. Re-running skips unchanged files — safe to run as often as you like.

Override the path with GNOSIS_MCP_DATABASE_URL=sqlite:///C:/path/to/docs.db (Windows) or sqlite:///~/custom/path/docs.db (Unix).

For PostgreSQL, set the URL first:

export GNOSIS_MCP_DATABASE_URL="postgresql://user:pass@localhost:5432/mydb"
gnosis-mcp init-db
gnosis-mcp ingest ./docs/

Preview what would be indexed without writing anything:

gnosis-mcp ingest ./docs/ --dry-run

Step 3: Verify

gnosis-mcp check    # verify database connection, schema, and FTS5
gnosis-mcp stats    # see document and chunk counts
gnosis-mcp search "getting started"   # test a search

check is the gate: it exits 0 only when the backend started and the tables the server needs are present, and it names whatever is missing before exiting 1. On SQLite it must print FTS5: ready — keyword search needs FTS5, which is compiled into your Python's SQLite rather than guaranteed by it. On a brand-new database check reports the schema as missing until the first init-db (or the first ingest, which creates the schema itself); after that, a non-zero exit means something is actually wrong — docs/troubleshooting.md.

Step 4: Connect to Your Editor

Add the MCP server config to your editor so your AI agent can search your docs.

Claude Code — add to .mcp.json at your project root:

{
  "mcpServers": {
    "docs": {
      "command": "gnosis-mcp",
      "args": ["serve"]
    }
  }
}

Claude Desktop — add to claude_desktop_config.json (~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows), then restart Claude Desktop:

{
  "mcpServers": {
    "docs": {
      "command": "gnosis-mcp",
      "args": ["serve"]
    }
  }
}

Cursor — add to .cursor/mcp.json:

{
  "mcpServers": {
    "docs": {
      "command": "gnosis-mcp",
      "args": ["serve"]
    }
  }
}

Windsurf — add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "docs": {
      "command": "gnosis-mcp",
      "args": ["serve"]
    }
  }
}

VS Code (GitHub Copilot) — add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "docs": {
      "command": "gnosis-mcp",
      "args": ["serve"]
    }
  }
}

Also discoverable via VS Code MCP gallery — search @mcp gnosis in Extensions view.

Zed — add to your settings.json (zed: open settings file). Zed's key is context_servers, not mcpServers:

{
  "context_servers": {
    "gnosis": {
      "command": "gnosis-mcp",
      "args": ["serve"]
    }
  }
}

Check the status dot under Settings → AI → MCP Servers — green means the server is active.

opencode — add to opencode.json in your project root (or ~/.config/opencode/opencode.json for every project). opencode's key is mcp, and the command is an array:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gnosis": {
      "type": "local",
      "command": ["gnosis-mcp", "serve"],
      "enabled": true
    }
  }
}

JetBrains (IntelliJ, PyCharm, WebStorm) — go to Settings > Tools > AI Assistant > MCP Servers, click +, set command to gnosis-mcp and arguments to serve.

Cline — open the Cline MCP settings panel and add the same server config.

For PostgreSQL, add an env block to any of the above (Zed takes the same env key; opencode calls it environment):

{
  "mcpServers": {
    "docs": {
      "command": "gnosis-mcp",
      "args": ["serve"],
      "env": {
        "GNOSIS_MCP_DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
      }
    }
  }
}

Optional: Enable Write Mode

By default a read-only client sees six tools — search_docs, get_doc, get_related, search_git_history, get_context, get_graph_stats. To let your AI agent create, update, and delete docs, set GNOSIS_MCP_WRITABLE=true, which adds the other three (upsert_doc, delete_doc, update_metadata) to tools/list:

{
  "mcpServers": {
    "docs": {
      "command": "gnosis-mcp",
      "args": ["serve"],
      "env": {
        "GNOSIS_MCP_WRITABLE": "true"
      }
    }
  }
}

Optional: Add Semantic Search

Keyword search works immediately. For semantic search (finding docs by meaning, not just keywords):

SQLite (local ONNX — no API key needed)

  1. Install with embeddings: pip install gnosis-mcp[embeddings]
  2. Ingest with embeddings: gnosis-mcp ingest ./docs/ --embed (downloads 23MB MongoDB/mdbr-leaf-ir on first run)
  3. Search with hybrid mode: gnosis-mcp search "how does billing work" --embed

Or embed existing chunks: gnosis-mcp embed (auto-detects local provider).

To get hybrid search for MCP tool calls (not just the CLI), set GNOSIS_MCP_EMBED_PROVIDER=local in the MCP server's env block. Without it, the server returns keyword-only results regardless of whether your chunks are embedded:

{
  "mcpServers": {
    "gnosis": {
      "command": "gnosis-mcp",
      "args": ["serve"],
      "env": {
        "GNOSIS_MCP_EMBED_PROVIDER": "local"
      }
    }
  }
}

Override the model with GNOSIS_MCP_EMBED_MODEL=<huggingface-repo-id> if you want something other than the default MongoDB/mdbr-leaf-ir. If auto-embed fails (network down, wrong model name, missing tokenizer), the server logs a warning and falls back to keyword-only — tool calls never crash because of it.

PostgreSQL (remote providers)

  1. Install with PostgreSQL: pip install gnosis-mcp[postgres]
  2. Enable pgvector: CREATE EXTENSION IF NOT EXISTS vector;
  3. Backfill embeddings: gnosis-mcp embed --provider openai (or --provider ollama for local Ollama)
  4. Search with --embed flag: gnosis-mcp search "how does billing work" --embed

Optional: Custom Search Function (PostgreSQL)

If you have a PostgreSQL function for hybrid semantic+keyword search:

{
  "env": {
    "GNOSIS_MCP_DATABASE_URL": "postgresql://...",
    "GNOSIS_MCP_SEARCH_FUNCTION": "my_schema.my_search_function"
  }
}

Your function must accept (p_query_text text, p_categories text[], p_limit integer) and return (file_path, title, content, category, combined_score).