MCP Server · stdio · fully offline

Your docs.
Claude's
memory.

Ask questions in plain English. Get cited answers from your own markdown files — deployment guides, runbooks, internal APIs — without uploading anything to the cloud.

claude — knowledge-base
0.000ndcg@10
SciFact (BEIR)
up from 0.652 in v1
0ms
median search time
same quality as qmd
0.0ρ
kb eval vs human labels
held-out dataset

Plain-English explanation

What does this
actually do?

The filing cabinet analogy
You hired a new employee and gave them a filing cabinet full of company documents. This tool is that cabinet, wired directly into Claude. Ask a question — it searches your actual files first, then gives you an answer with an exact citation. Like a librarian who says "page 47, third paragraph."
Term
MCP — Model Context Protocol
Anthropic's open standard that lets Claude Desktop talk to external tools. Like a USB port — you plug in a tool and Claude can use it. This project is one such tool, called an "MCP server."
Term
Semantic Search
Old search finds exact words. Semantic search understands meaning. "How do I fix a broken deploy?" finds "Rollback Procedure" — even though "fix" and "broken" don't appear in the title.
Term
Vector Embedding
Each document chunk becomes 384 numbers representing its meaning. Your query becomes numbers too. We find the chunks whose numbers are closest. That's semantic search under the hood.
Term
Citation [source: file.md:L18]
Every answer includes the exact file and line number. Open it, verify it, notice when docs are out of date. A system that gives answers without sources can't be trusted professionally.

Architecture

Five components.
One pipeline.

Here's exactly what each piece does, in plain terms.

01
Your markdown files
Put all your documentation in a folder — deployment guides, API references, onboarding docs. They're just regular .md text files. This is your raw knowledge.
./your-docs/*.md
02
The indexer — kb index
Cuts each file into chunks of at most 256 tokens (exactly what the embedding model can read), labels each with its file > heading, and files it twice: as 384 numbers capturing its meaning, and as words for keyword search. Re-runs only touch files whose content changed.
kb index ./your-docs
03
Two catalogues on your disk
Meanings go into ChromaDB, words into a BM25 index in SQLite. Meaning search finds paraphrases ("undo a deploy" → "rollback"); keyword search finds exact names and codes. Nothing goes online.
~/.mcp-kb/chroma/ — local disk only
04
The MCP server — kb serve
Runs in the background, listens for Claude Desktop. Exposes two tools: search_docs (top 50 by meaning + top 50 by words, merged by rank, then a careful re-read of the top 20 by a reranker) and list_docs. If nothing scores as clearly relevant, it says so.
kb serve --docs ./your-docs — stdio transport
05
Claude Desktop uses the tools
You ask "how do I roll back a bad deploy?" Claude calls search_docs, gets back 5 relevant chunks with file names and line numbers, then writes you an answer using that real information.
[source: deployment-runbook.md:L18-L24]
0
nDCG@10 · SciFact (BEIR) · 300 human-written questions
Measured, not claimed

Measured honestly,
losses included.

nDCG@10 asks: when you search, are the right documents at the very top? 1.0 = perfect ranking.

Every change was benchmarked on three public BEIR datasets and kept only if a significance test said the gain was real: +10% on SciFact and +18% on NFCorpus over v1, level on FiQA. The results page also lists what didn't work.

0.720
nDCG@10
Dataset
SciFact, BEIR test split
Corpus
5,183 scientific abstracts
Queries
300 human-written questions
Fairness
same files, queries and scoring for every tool
qmd (LLM expansion + rerank) · 7.1 s per search 0.729
kb, this project · 67 ms per search 0.720
knowledge-rag · 224 ms per search 0.718
BM25 keyword search alone 0.685
v1 of this project 0.652

The top three are a statistical tie (p > 0.5). On NFCorpus, qmd is ahead (0.383 vs 0.364, p = 0.02) thanks to LLM query rewriting, at about 85× the latency. qmd's GPU backend failed to compile on the test machine, so its latency is likely CPU-bound.


Audience

Built for teams whose
docs can't leave the building.

Engineering teams
You have private runbooks
Deployment guides, incident playbooks, on-call procedures. Things nobody can find when the site is down at 2am. Index once, ask Claude anytime.
Security-conscious orgs
You can't upload to GPT
Legal docs, internal specs, unreleased features. Compliance teams can approve this — nothing leaves the machine. No vendor agreement to negotiate.
Solo developers
You want AI over your own notes
Engineering journals, personal knowledge bases, project notes. Make Claude aware of everything you've written without pasting it into every conversation.
MCP builders
You're learning the protocol
A complete working MCP server: tool registration, stdio transport, Arize Phoenix observability. 200 lines. Read the source. Build on top of it.
No cloud account needed
Docs stay on your machine
Every answer cited
Works offline after setup
5-minute install
Zero API keys

Quickstart

Running in five
minutes.

Three commands to get Claude Desktop searching your docs.

Terminal
# 1. Clone and install
git clone https://github.com/karthikreddyyalala/MCP_Knowledge_Base.git
cd MCP_Knowledge_Base && uv venv && uv pip install -e .

# 2. Index your docs (once)
.venv/bin/kb index ./your-docs

# 3. Add to Claude Desktop
# ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "knowledge-base": {
      "command": "/absolute/path/to/MCP_Knowledge_Base/.venv/bin/kb",
      "args": ["serve", "--docs", "/path/to/your-docs"]
    }
  }
}

# Restart Claude Desktop.
# Hammer icon appears → you're live.
# Ask: "What docs do you have access to?"