kb-mcp

An agent-native knowledge base.

pip install kb-mcp — give any LLM agent a structured, queryable, local-first second brain.

The problem

Knowledge bases for humans (Notion, Obsidian) and for search engines (Elasticsearch, vector DBs) leave a gap: LLM agents need a knowledge layer that speaks their protocol and assumes the reader is a model, not a person.

kb-mcp fills it.

Related MCP server: vault-memory

Features

• 🧠 Agent-native. Every document is reachable from any MCP client (Claude Desktop, Cursor, OpenCode, Codex, …) via kb_search / kb_get / kb_add / kb_link.

• 📐 Schema-first. Six built-in document types (project, decision, lesson, glossary, person, faq) — extensible via Python subclassing.

• 🔍 Full-text search. SQLite FTS5 with BM25 ranking. Snippet-aware results returned to the agent.

• 🔗 Typed links. Documents reference other documents; backlinks are automatic.

• 📝 Markdown friendly. Round-trip import/export with frontmatter. Humans can edit, agents can read.

• 🪶 Zero deps by default. SQLite ships with Python. pip install kb-mcp and you're done.

• 🔒 Local-first. Your data lives in ~/.local/share/kb-mcp/. No cloud, no telemetry, no phone-home.

Quickstart

pip install kb-mcp
kb init
kb add --type project --title "kb-mcp" --tags kb,mcp,open-source --body "Agent-native knowledge base."
kb search "mcp server"

# Expose to any MCP client
kb serve

That's it. Five commands, zero config files.

👉 Full walkthrough: docs/quickstart.md

Document types

Subclass kb_mcp.schema.Document to add your own.

MCP integration

Add to ~/.config/claude_desktop_config.json (or any MCP client):

{
  "mcpServers": {
    "kb": {
      "command": "kb",
      "args": ["serve"]
    }
  }
}

The agent then sees four tools:

• kb_search(query, type?, tags?, limit?) — BM25-ranked results with snippets

• kb_get(id) — full document by id (or slug)

• kb_add(type, title, body, tags?, source?) — create document

• kb_link(from_id, to_id, rel?) — typed edge between documents

Development

git clone https://github.com/your-org/kb-mcp
cd kb-mcp
pip install -e ".[dev]"
pytest          # unit + E2E (real SQLite temp file, no mocks)
ruff check .
mypy src/

👉 Spec: docs/requirements.md · Architecture: docs/architecture.md · CLI reference: docs/cli-reference.md

Roadmap

See docs/requirements.md § 4 for v0.1 scope decisions and out-of-scope list.

Status

alpha. API and storage format may change before v0.2.0. Pin minor versions (kb-mcp>=0.1,<0.2) in production.

Contributing

Issues and PRs welcome. See CONTRIBUTING.md (TODO before v0.1.0 release).

By participating, you agree to abide by the Code of Conduct (TODO before v0.1.0 release).

License

MIT — do what you want, just keep the copyright notice.