Getting started

rag-hub-mcp is a self-hosted RAG server. It turns folders of documents into named knowledge bases, then exposes them to AI agents over MCP and to any tool over a small REST API.

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

Quick start (stdio)

Run it directly with npx — no install, no server to keep running:

npx rag-hub-mcp

stdio mode serves the MCP tools on stdin/stdout for a local agent. Point it at a folder of documents:

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

Or install globally once:

npm install -g rag-hub-mcp
rag-hub-mcp          # stdio
rag-hub-mcp --http   # server

Quick start (HTTP server)

For a shared server reachable over the network (REST API + MCP over streamable-http) or a Docker deployment:

mkdir -p ./kbs/my-knowledge-base
echo "Hello RAG" > ./kbs/my-knowledge-base/hello.md

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

Verify:

curl http://localhost:8000/health
curl -H "Authorization: Bearer my-secret-key" http://localhost:8000/admin/kbs

Docker

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

The image is multi-arch (linux/amd64, linux/arm64). Or build it yourself:

docker build -t rag-hub-mcp .

Next steps

• Architecture — how indexing and search work.
• MCP Tools — the 9 tools your agents get.
• REST API — the /search and /admin/* endpoints.
• Configuration — environment variables and embedding models.
• Integrations — wire up opencode, Claude Code, Cline, dsh.
• End-to-end example — drive a KB entirely from a chat.