rag-hub-mcp

Self-hosted RAG that speaks MCP. Drop folders, get a knowledge base. Zero infrastructure.

Drop documents into folders → each folder becomes a named knowledge base → search them from any MCP-compatible agent (Claude Code, OpenCode, Cline…) or over a tiny REST API. Your data stays on your machine — there's no vector database to run. A PostgreSQL + pgvector backend is also available as an opt-in for server-side deployments.

Full documentation: openhoat.github.io/rag-hub-mcp

Why rag-hub-mcp?

Most RAG setups need a vector database, a chunking pipeline, an embeddings service and glue code. rag-hub-mcp collapses all of that into one process:

• Folders are knowledge bases — a 1st-level folder is a KB, named after the folder. No schema, no UI.

• Zero infrastructure — one SQLite database with FTS5 by default. No vector DB, no server to keep running. (Optional PostgreSQL + pgvector backend for server-side deployments.)

• MCP-native — 10 tools over the Model Context Protocol, so any agent can use it in seconds.

• Hybrid search — vector cosine similarity fused with full-text keyword search (SQLite FTS5 or PostgreSQL ts_rank).

Related MCP server: kbdb

How it works

./kbs/ — folders = knowledge bases
  │
  │  scan (SHA-256 diff) → enqueue index jobs
  ▼
worker (async, concurrent) → extract → chunk → embed
  │  bge-m3 / any OpenAI-compatible API
  ▼
┌─────────────────────────────┐
│  SQLite + FTS5              │
│  or PostgreSQL + pgvector   │
└─────────────────────────────┘
  │
  │  hybrid score
  │  cosine 0.65 + FTS 0.35
  ▼
┌──────────────┐  ┌──────────────┐
│  MCP tools   │  │  REST API    │
│  stdio/http  │  │  /search     │
└──────────────┘  └──────────────┘

Install

No install needed — run it directly with npx:

# stdio mode (default): serve MCP tools for a local agent
npx @headwood/rag-hub-mcp

# HTTP mode: REST API + MCP (streamable-http) on a port
npx @headwood/rag-hub-mcp --http

Requires Node 22+. better-sqlite3 compiles natively on first use (prebuilt binaries are used when available).

Quick start

mkdir -p ./kbs/my-knowledge-base
echo "Hello RAG" > ./kbs/my-knowledge-base/hello.md
npx @headwood/rag-hub-mcp

Any MCP-compatible agent can launch the server itself via npx — no server to keep running:

{
  "mcpServers": {
    "rag-hub-mcp": {
      "command": "npx",
      "args": ["@headwood/rag-hub-mcp"],
      "env": {
        "EMBEDDINGS_BASE_URL": "http://localhost:11434/v1",
        "EMBEDDINGS_MODEL": "bge-m3",
        "KB_ROOT": "./kbs",
        "DB_PATH": "./rag.db"
      }
    }
  }
}

The 10 rag_* tools are then available in your agent sessions.

HTTP server / Docker

For a shared server over the network or a Docker deployment, see getting started. In short:

MCP_API_KEY=my-secret-key EMBEDDINGS_BASE_URL=http://localhost:11434/v1 \
  KB_ROOT=./kbs npx @headwood/rag-hub-mcp --http

docker run -p 8000:8000 -e MCP_API_KEY=my-secret-key \
  -e EMBEDDINGS_BASE_URL=http://host.docker.internal:11434/v1 ghcr.io/openhoat/rag-hub-mcp:latest

MCP tools & REST API

10 tools over MCP, callable from any MCP-compatible agent:

Small REST API (--http mode), all endpoints except /health require MCP_API_KEY:

See the MCP tools and REST API docs for the full detail.

Configuration

Set via environment variables (MCP_API_KEY, EMBEDDINGS_BASE_URL, EMBEDDINGS_MODEL, KB_ROOT, DB_PATH, …). See the configuration docs for the full table.

Roadmap

• Native pgvector similarity search in the PostgreSQL backend (<=> / LIMIT k)

• Streaming search results over MCP

• Web UI dashboard (stats, documents, live search)

• Reranking of hybrid results

• Multi-tenant / shared deployments

Documentation

The full docs live at openhoat.github.io/rag-hub-mcp — getting started, architecture, MCP tools, REST API, integrations, and an end-to-end example.

Development

npm install
npm run build           # compile to dist/build/
npm run validate        # qa (lint + typecheck + test:coverage) + build
npm run clean           # remove build artifacts (dist/build/)
npm start               # start the server (stdio, from dist/build/)
npm run start:dev       # start the server directly from TS (no build)
npm start -- --http     # start in HTTP mode (REST + streamable-http MCP)
npm run start:inspector # open the MCP Inspector web UI (launches via tsx, no build)

Uses Biome for linting/formatting and vitest for unit + e2e tests. The source is split into domain modules (shared/, embeddings/, storage/, indexing/, search/, transport/) — see the architecture doc for the full picture. Contributions are welcome.

License

MIT