Gnosis MCP — Installation Guide

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.

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
gnosis-mcp stats    # see document and chunk counts
gnosis-mcp search "getting started"   # test a search

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 .claude/mcp.json:

{
  "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.

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:

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

Optional: Enable Write Mode

By default, only read tools (search, get, related) are enabled. To let your AI agent create, update, and delete docs:

{
  "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 model 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)

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).