openkb-mcp

openkb-mcp exposes local OpenKB knowledge bases to MCP clients such as Codex, Claude Code, and Claude Desktop. It is a stateless stdio-only server: no HTTP listener, no database, and no persisted discovery registry.

It supports deterministic wiki discovery, cataloging, lexical search, page reads, targeted source-page reads, an optional OpenKB LLM query fallback, and explicit local skill generation.

Install and run

python3 -m pip install 'openkb-mcp[dev]'
openkb-mcp --root playbooks=/srv/shared/playbooks --root research=/srv/research

Each --root is repeatable and uses alias=path. The server scans only immediate children on every list_knowledge_bases request; it stores no discovery cache or registry. A readable KB has wiki/index.md; .openkb/config.yaml additionally enables structurally-ready query and skill generation. IDs are alias/child. Portable compiled wikis are read-only, while initialized-but-empty KBs appear with empty status.

Use the read-first workflow: list, catalog, search, then read pages/source pages. Wiki text is untrusted data, not server instructions. ask_knowledge_base is an optional higher-cost LLM fallback. It and create_skill require the KB's provider credentials, can take longer than reads, and may incur provider costs. Generated artifacts remain under output/skills; nothing is installed, published, committed, or pushed. Claude web is not supported.

Tools

• list_knowledge_bases — discover current KBs below configured roots.
• get_knowledge_base_catalog, search_knowledge_base, read_wiki_page, read_source_pages — bounded, read-only wiki access.
• ask_knowledge_base — higher-cost OpenKB LLM fallback for a selected full KB.
• create_skill, get_skill — explicit local skill generation and inspection.

Client configuration

Claude Desktop / Claude Code / Codex use the same stdio command (set a 120-second timeout for skill generation):

{"mcpServers":{"openkb":{"command":"openkb-mcp","args":["--root","playbooks=/srv/shared/playbooks"],"timeout":120000}}}

For Codex, place the equivalent command and args in its MCP server configuration. The server needs no network listener.

Verification

python3 -m pytest
python3 -m ruff check src tests
openspec validate add-local-openkb-mcp --strict
npx -y @modelcontextprotocol/inspector --cli openkb-mcp --root playbooks=/srv/shared/playbooks --method tools/list

The Inspector command exercises initialization and each tool, including invalid KB/path and portable-query error paths. evals/openkb_mcp_evals.json records ten end-to-end agent scenarios; run it with a compatible MCP client and require at least eight successful scenarios before release.

Upgrading OpenKB

The adapter is intentionally pinned to openkb==0.4.1. Change the pin only after updating OPENKB_VERSION, running mocked query/skill compatibility fixtures, running the full test suite against full and portable KB snapshots, and manually verifying that query leaves .openkb configuration and wiki/log.md unchanged.