gnosis-mcp 0.6.0

Zero-config MCP server for searchable documentation (SQLite default, PostgreSQL optional)

Gnosis MCP

Give your AI agent a searchable knowledge base. Zero config.

Quick Start · Choose Your Backend · Claude Code Plugin · What It Does · Configuration · Full Reference · Docs

---

AI coding agents can read your source code but not your documentation. They guess at architecture, miss established patterns, and hallucinate details they could have looked up.

Gnosis MCP fixes this. It loads your markdown docs into a database and exposes them as MCP tools — search, read, and manage — that any compatible agent can call. Claude Code, Cursor, Windsurf, Cline, VS Code.

Zero config. Install, point at a folder, search. Works with SQLite out of the box — no database server needed. Scale up to PostgreSQL + pgvector when you're ready.

What you get

Less hallucination. Agents search your docs before guessing. When the billing rules, API contracts, or architecture decisions are one tool call away, the agent uses them instead of making things up.

Lower token costs. A targeted search returns ~600 tokens of ranked snippets. Loading the same information by reading full files costs 3,000-8,000+ tokens. On a knowledge base with 170 docs (~840K tokens total), that's the difference between finding the right answer and blowing your context window.

Docs that stay useful. New docs are searchable the moment you ingest them. No manual routing tables to maintain, no hardcoded file paths to update. Agents discover docs dynamically through search, not through stale indexes.

One search, full coverage. FTS5 keyword search works out of the box. Add PostgreSQL + pgvector for hybrid keyword+semantic search when you need it.

Quick Start

pip install gnosis-mcp
gnosis-mcp ingest ./docs/       # load your markdown (auto-creates SQLite database)
gnosis-mcp serve                # start MCP server

That's it. Two commands. No database server, no connection strings, no config files.

Or without installing:

uvx gnosis-mcp serve

Connect your editor

Claude Code — add to .claude/mcp.json:

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

Cursor, Windsurf, Cline

Same JSON structure. Place it in:

• Cursor: .cursor/mcp.json
• Windsurf: ~/.codeium/windsurf/mcp_config.json
• Cline: Cline MCP settings panel

Choose Your Backend

	SQLite (default)	PostgreSQL
Install	pip install gnosis-mcp	pip install gnosis-mcp[postgres]
Config	Nothing — works immediately	Set DATABASE_URL
Search	FTS5 keyword (BM25)	tsvector + pgvector hybrid
Embeddings	Stored as binary blobs	Native vector type + HNSW index
Multi-table	No	Yes (UNION ALL across tables)
Best for	Personal projects, demos, single-user	Teams, production, semantic search

Auto-detection: Set DATABASE_URL to postgresql://... and it uses PostgreSQL. Don't set it and it uses SQLite. Override with GNOSIS_MCP_BACKEND=sqlite|postgres.

PostgreSQL setup

pip install gnosis-mcp[postgres]
export GNOSIS_MCP_DATABASE_URL="postgresql://user:pass@localhost:5432/mydb"
gnosis-mcp init-db
gnosis-mcp ingest ./docs/
gnosis-mcp serve

For hybrid search with pgvector:

CREATE EXTENSION IF NOT EXISTS vector;

Claude Code Plugin

Install as a Claude Code plugin to get the MCP server, skills, and health check hook in one step:

claude plugin marketplace add nicholasglazer/gnosis-mcp
claude plugin install gnosis

This gives you:

Component	What you get
MCP server	gnosis-mcp serve — auto-configured
/gnosis:search	Search docs with keyword or --semantic hybrid mode
/gnosis:status	Health check — connectivity, doc stats, troubleshooting
/gnosis:manage	CRUD — add, delete, update metadata, bulk embed
The plugin works with both SQLite and PostgreSQL backends.

Manual setup (without plugin)

Add to .claude/mcp.json:

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

For PostgreSQL, add "env": {"GNOSIS_MCP_DATABASE_URL": "postgresql://..."}.

What It Does

Gnosis MCP provides 6 tools and 3 resources over MCP.

Tools

Tool	What it does	Mode
search_docs	Keyword or hybrid semantic+keyword search	Read
get_doc	Retrieve a full document by path	Read
get_related	Find linked documents	Read
upsert_doc	Create or replace a document	Write
delete_doc	Remove a document	Write
update_metadata	Change title, category, tags	Write

Write tools require GNOSIS_MCP_WRITABLE=true. Read tools are always on.

Resources

URI	Returns
gnosis://docs	All documents — path, title, category, chunk count
gnosis://docs/{path}	Full document content
gnosis://categories	Categories with doc counts

Search

Three modes, one tool:

# Keyword — fast, exact matches (works on both backends)
gnosis-mcp search "stripe webhook"

# Hybrid — keyword + semantic similarity (PostgreSQL with embeddings)
gnosis-mcp search "how does billing work" --embed

# Filtered — narrow by category
gnosis-mcp search "auth" -c guides

When called via MCP, pass query_embedding for hybrid mode. Without it, you get keyword search.

Embeddings

Gnosis MCP handles embeddings in three tiers, all without adding dependencies:

Accept pre-computed vectors — pass embeddings to upsert_doc or query_embedding to search_docs if you generate them externally.

Backfill with the CLI — find chunks missing embeddings and fill them:

gnosis-mcp embed --dry-run              # see what needs embedding
gnosis-mcp embed                        # backfill via OpenAI (default)
gnosis-mcp embed --provider ollama      # or use local Ollama

Supports OpenAI, Ollama, and any OpenAI-compatible endpoint. Uses stdlib urllib.request — no new runtime deps.

Built-in hybrid scoring — on PostgreSQL, when query_embedding is provided, search automatically combines keyword (tsvector) and cosine similarity using reciprocal rank fusion.

Configuration

All settings via environment variables. No config files required.

Variable	Default	Description
GNOSIS_MCP_DATABASE_URL	SQLite auto	PostgreSQL URL or SQLite path
GNOSIS_MCP_BACKEND	auto	Force sqlite or postgres
GNOSIS_MCP_SCHEMA	public	Database schema (PostgreSQL)
GNOSIS_MCP_CHUNKS_TABLE	documentation_chunks	Chunks table name
GNOSIS_MCP_SEARCH_FUNCTION	—	Custom search function (PostgreSQL)
GNOSIS_MCP_EMBEDDING_DIM	1536	Vector dimension for init-db
GNOSIS_MCP_WRITABLE	false	Enable write tools
GNOSIS_MCP_TRANSPORT	stdio	Transport: stdio or sse

All variables

Search & chunking: GNOSIS_MCP_CONTENT_PREVIEW_CHARS (200), GNOSIS_MCP_CHUNK_SIZE (4000), GNOSIS_MCP_SEARCH_LIMIT_MAX (20).

Connection pool (PostgreSQL): GNOSIS_MCP_POOL_MIN (1), GNOSIS_MCP_POOL_MAX (3).

Webhooks: GNOSIS_MCP_WEBHOOK_URL, GNOSIS_MCP_WEBHOOK_TIMEOUT (5s).

Embeddings: GNOSIS_MCP_EMBED_PROVIDER (openai/ollama/custom), GNOSIS_MCP_EMBED_MODEL, GNOSIS_MCP_EMBED_API_KEY, GNOSIS_MCP_EMBED_URL, GNOSIS_MCP_EMBED_BATCH_SIZE (50).

Column overrides (for existing tables with non-standard names): GNOSIS_MCP_COL_FILE_PATH, GNOSIS_MCP_COL_TITLE, GNOSIS_MCP_COL_CONTENT, GNOSIS_MCP_COL_CHUNK_INDEX, GNOSIS_MCP_COL_CATEGORY, GNOSIS_MCP_COL_AUDIENCE, GNOSIS_MCP_COL_TAGS, GNOSIS_MCP_COL_EMBEDDING, GNOSIS_MCP_COL_TSV, GNOSIS_MCP_COL_SOURCE_PATH, GNOSIS_MCP_COL_TARGET_PATH, GNOSIS_MCP_COL_RELATION_TYPE.

Links table: GNOSIS_MCP_LINKS_TABLE (documentation_links).

Logging: GNOSIS_MCP_LOG_LEVEL (INFO).

Custom search function (PostgreSQL)

Delegate search to your own PostgreSQL function for custom ranking:

CREATE FUNCTION my_schema.my_search(
    p_query_text text,
    p_categories text[],
    p_limit integer
) RETURNS TABLE (
    file_path text, title text, content text,
    category text, combined_score double precision
) ...

GNOSIS_MCP_SEARCH_FUNCTION=my_schema.my_search

Multi-table mode (PostgreSQL)

Query across multiple doc tables:

GNOSIS_MCP_CHUNKS_TABLE=documentation_chunks,api_docs,tutorial_chunks

All tables must share the same schema. Reads use UNION ALL. Writes target the first table.

CLI Reference

gnosis-mcp serve [--transport stdio|sse] [--ingest PATH]   Start MCP server
gnosis-mcp init-db [--dry-run]                             Create tables + indexes
gnosis-mcp ingest <path> [--dry-run]                       Load markdown files
gnosis-mcp search <query> [-n LIMIT] [-c CAT] [--embed]    Search docs
gnosis-mcp embed [--provider P] [--model M] [--dry-run]    Backfill embeddings
gnosis-mcp stats                                           Document/chunk counts
gnosis-mcp export [-f json|markdown] [-c CAT]              Export documents
gnosis-mcp check                                           Verify DB connection

Development

git clone https://github.com/nicholasglazer/gnosis-mcp.git
cd gnosis-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest                    # 176 tests, no database needed
ruff check src/ tests/

Architecture

src/gnosis_mcp/
├── backend.py         DocBackend protocol + create_backend() factory
├── pg_backend.py      PostgreSQL backend — asyncpg, tsvector, pgvector
├── sqlite_backend.py  SQLite backend — aiosqlite, FTS5
├── sqlite_schema.py   SQLite DDL — tables, FTS5, triggers
├── config.py          Frozen dataclass, env vars, backend auto-detection
├── db.py              Backend lifecycle + FastMCP lifespan
├── server.py          FastMCP server — 6 tools, 3 resources, webhooks
├── ingest.py          Markdown scanner — H2 chunking, frontmatter, content hashing
├── schema.py          PostgreSQL DDL — tables, indexes, search functions
├── embed.py           Embedding sidecar — provider abstraction, batch backfill
└── cli.py             CLI — serve, init-db, ingest, search, embed, stats, export, check

Zero config by default. Install and run — SQLite handles everything. Set a DATABASE_URL to upgrade to PostgreSQL + pgvector for hybrid search and multi-table support. Backend protocol keeps the abstraction clean: PostgreSQL and SQLite each use natural SQL in their own dialect.

AI-Friendly Docs

File	For
llms.txt	Quick overview — tools, config, schema
llms-full.txt	Complete reference in one file
llms-install.md	Step-by-step install guide

Contributing

git clone https://github.com/nicholasglazer/gnosis-mcp.git && cd gnosis-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]" && pytest

All tests run without a database. Keep it that way.

Good first contributions: new embedding providers, export formats, ingestion for RST/AsciiDoc/HTML, search highlighting. Open an issue first for larger changes.

Sponsors

If Gnosis MCP saves you time, consider sponsoring the project.

License

MIT