MCP Knowledge Base Server

An MCP (Model Context Protocol) server that gives AI assistants — Claude Desktop, Cursor, or any MCP client — searchable, structured access to a company's internal knowledge base of Markdown documents.

Ask your assistant "how do I deploy to production?" or "how many vacation days do I get?" and it will search the knowledge base, read the relevant articles, and answer with citations — instead of hallucinating your internal processes.

Features

• 6 tools — keyword search with snippets, full-document fetch, filtered listing, tag browsing, hot reload, and stats
• 2 resource types — browse the whole index or any document directly (kb://index, kb://documents/{doc_id})
• 1 prompt template — answer_from_knowledge_base grounds answers in search results and forces citations
• Zero-infrastructure — the knowledge base is just a folder of .md files with optional frontmatter; works great backed by a Git repo
• Two transports — stdio for local clients, HTTP for shared/remote setups
• Dependency-light — FastMCP + a small built-in TF-IDF-style index; no database, no embeddings service required

Architecture

┌─────────────────┐   stdio / HTTP (JSON-RPC)   ┌──────────────────────────┐
│  MCP client     │ ───────────────────────────▶ │  FastMCP server          │
│  (Claude, …)    │ ◀─────────────────────────── │  ├─ tools (search, get…) │
└─────────────────┘                              │  ├─ resources (kb://…)   │
                                                 │  └─ prompts (answer…)   │
                                                 │          │             │
                                                 │  KnowledgeBaseIndex    │
                                                 │  (tokenize → TF-IDF)   │
                                                 └──────────┬─────────────┘
                                                            │ scans
                                                 ┌──────────▼─────────────┐
                                                 │ knowledge_base/        │
                                                 │  engineering/*.md      │
                                                 │  hr/*.md  product/*.md │
                                                 └────────────────────────┘

Quickstart

git clone <your-repo-url> mcp-knowledge-base-server
cd mcp-knowledge-base-server
pip install .

Point the server at your own docs (or use the included sample corpus):

export KB_DIR=/path/to/your/markdown/docs

Run the demo

pip install fastmcp          # only dependency the demo needs
python examples/demo_client.py

The demo spawns the server over stdio and exercises every capability — search, document fetch, listing, resources, and the grounded-answer prompt — printing the exact JSON-RPC payloads a real client would see.

Connect Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "knowledge-base": {
      "command": "python",
      "args": ["-m", "mcp_knowledge_base.server"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/mcp-knowledge-base-server/src",
        "KB_DIR": "/absolute/path/to/mcp-knowledge-base-server/knowledge_base"
      }
    }
  }
}

Restart Claude Desktop, then ask: "Search our knowledge base — what's the rollback procedure if a deploy goes wrong?"

Run over HTTP (shared/remote setups)

KB_DIR=/path/to/docs mcp-knowledge-base --transport http --port 8000
# → streamable HTTP endpoint at http://127.0.0.1:8000/mcp

Document format

Any folder of .md files works. Optional frontmatter enriches results:

---
title: Deploying to Production
tags: [deploy, production, runbook]
department: engineering
updated: 2025-11-02
---

# Deploying to Production
…

The document doc_id is its path relative to KB_DIR without the extension (e.g. engineering/deploy-guide). Title falls back to the first # heading, then the filename.

API reference

Tools

Tool	Description
search_knowledge_base(query, limit=5, tag=None)	Ranked keyword search; returns doc_id, title, tags, snippet, score
get_document(doc_id)	Full Markdown content + metadata of one article
list_documents(tag=None, department=None)	List all articles, optionally filtered
list_tags()	All tags with document counts
reload_knowledge_base()	Re-scan KB_DIR to pick up edits
stats()	Document count, tag count, index age

Resources

URI	Description
kb://index	Human-readable index of every document
kb://documents/{doc_id}	Full content of one document

Prompts

Prompt	Description
answer_from_knowledge_base(question)	Searches the KB, then instructs the model to answer only from the excerpts and cite doc_ids

Environment variables

Variable	Default	Description
KB_DIR	./knowledge_base	Root folder of Markdown documents
KB_NAME	Company Knowledge Base	Server name shown to MCP clients

Project structure

├── knowledge_base/            # sample corpus (replace with your own)
│   ├── engineering/*.md
│   ├── hr/*.md
│   └── product/*.md
├── src/mcp_knowledge_base/
│   ├── server.py              # FastMCP server: tools, resources, prompts
│   └── index.py               # document loading + TF-IDF-style search
├── examples/
│   └── demo_client.py         # end-to-end demo over stdio
└── pyproject.toml

Extending it

• Better search: swap KnowledgeBaseIndex for embeddings + a vector DB (the tool interface stays identical).
• Other sources: index Confluence/Notion exports — anything that ends up as Markdown works unchanged.
• Freshness: run reload_knowledge_base on a schedule, or watch KB_DIR with a filesystem watcher.

License

MIT — see LICENSE.