kb-mcp-server

A portable knowledge management MCP server for Claude Code. Gives Claude persistent, searchable project knowledge that grows over time.

What it does

kb-mcp-server indexes your project's markdown documentation and makes it searchable via semantic (meaning-based) and keyword search. Claude Code uses this to:

• Look up domain knowledge, architecture patterns, and gotchas before making changes
• Capture new knowledge discovered during tasks
• Track documentation health and coverage gaps

Search is multilingual — Dutch queries find English documents and vice versa.

Quick start

# Install globally
npm install -g kb-mcp-server

# In your project directory
kb-mcp init

# Restart Claude Code — the MCP server starts automatically

The init command creates:

• kb/ directory with domain/, technical/, operational/ subdirectories
• .kbrc.json configuration
• .mcp.json entry so Claude Code starts the server automatically
• .claude/skills/ with 5 Claude Code skills

On first startup, the embedding model (~120MB) downloads automatically and is cached for offline use.

Skills

After setup, these slash commands are available in Claude Code:

| Skill | Purpose | |-------|---------| | /kb-setup | Guided onboarding — scans your project and seeds the KB | | /kb-lookup | Search with context enrichment and confidence interpretation | | /kb-capture | Capture knowledge from the current task | | /kb-health | Review KB health metrics and coverage | | /kb-optimize | Improve document quality |

MCP Tools

The server exposes 8 tools via the MCP protocol:

| Tool | Description | |------|-------------| | kb-query | Semantic + keyword search with confidence scores | | kb-list-topics | List documented topics and categories | | kb-get-document | Retrieve a document's full content | | kb-add-document | Create a new KB document | | kb-update-document | Update an existing document | | kb-index-status | Index statistics (doc count, model status) | | kb-health-report | Coverage metrics, miss rate, stale docs | | kb-analyze-docs | Document quality analysis |

How search works

Three signals combined per query:

1. Vector similarity (60%) — Embeds your query and finds semantically similar chunks using cosine similarity
2. Chunk FTS (25%) — BM25 keyword matching on document sections
3. Document FTS (15%) — Frontmatter keyword boost (title, summary, keywords)

Documents are split into chunks by H2/H3 headings. Each chunk carries its heading context for better relevance.

Configuration

All options in .kbrc.json:

{
  "docsPath": "./kb",
  "watchPaths": ["./kb"],
  "indexPath": "./.kb-data/kb.db",
  "model": "Xenova/paraphrase-multilingual-MiniLM-L12-v2",
  "debounceMs": 300,
  "chunkingThreshold": 50,
  "weights": { "vector": 0.6, "chunkFts": 0.25, "documentFts": 0.15 },
  "confidenceThresholds": { "high": 0.8, "low": 0.4 }
}

See docs/configuration.md for full reference.

Docker

docker build -t kb-mcp-server .

See docker-compose.example.yml for volume mounts and Claude Code integration via the stdio bridge script.

CLI commands

kb-mcp init             # Initialize KB in current directory
kb-mcp serve            # Start MCP server (usually done by Claude Code)
kb-mcp status           # Show index statistics
kb-mcp reindex          # Force full re-index
kb-mcp upgrade          # Update skills to latest version
kb-mcp download-model   # Pre-download embedding model

System requirements

| Resource | Requirement | |----------|-------------| | Node.js | 20+ | | RAM | ~300-400MB (embedding model) | | Disk | ~150MB (model cache) + KB database | | OS | macOS, Linux, Windows |

Documentation

• Getting Started
• Configuration Reference
• Skills Reference
• Architecture

Credits

This project is built on the work of these excellent open source projects:

| Project | Author | What it provides | |---------|--------|------------------| | Transformers.js | Hugging Face | Embedding model runtime (ONNX) | | paraphrase-multilingual-MiniLM-L12-v2 | Sentence-Transformers / Nils Reimers & Iryna Gurevych | Multilingual embedding model | | MCP SDK | Anthropic | Model Context Protocol implementation | | better-sqlite3 | Joshua Wise | Fast, synchronous SQLite bindings for Node.js | | sqlite-vec | Alex Garcia | Vector search extension for SQLite | | Chokidar | Paul Miller | Cross-platform file watching | | Commander.js | TJ Holowaychuk | CLI framework | | gray-matter | Jon Schlinkert | YAML frontmatter parsing | | Zod | Colin McDonnell | TypeScript schema validation |

License

MIT