Knowledge

Knowledge is an MCP server for people who run their own knowledge base. It lets an AI assistant search, read and write the notes in it, from one install.

It is a bundle: one server made of modules. You switch on the modules you use. New modules arrive switched off, so an update never changes what your assistant can do until you choose to.

Audience: people who self-host Open Notebook and want their assistant to use it.

Knowledge works with any MCP client: Claude Desktop, Claude Code, Cursor, VS Code, Sonique, Hermes, OpenClaw and others. It runs on your computer and stores nothing. Your notes stay in your Open Notebook server.

Install

Knowledge needs Python 3.11 or newer. With uv you don't install anything ahead of time:

uvx knowledge-bundle-mcp --version

Or with pip:

pip install knowledge-bundle-mcp

Settings

Set these as environment variables in your MCP client's config, or put them in a config file (see below). Knowledge starts without any of them and tells you what's missing when you call a tool.

Config file (optional). Knowledge also reads ~/.config/knowledge/config.toml, or the file named by KNOWLEDGE_CONFIG. Environment variables win over the file.

[open_notebook]
url = "https://notebook.example.com"
password = "change-me"
require_confirm = true

Add it to your MCP client

Most clients use the same JSON shape. Put it where your client keeps MCP servers:

{
  "mcpServers": {
    "knowledge": {
      "command": "uvx",
      "args": ["knowledge-bundle-mcp"],
      "env": {
        "KNOWLEDGE_OPEN_NOTEBOOK_URL": "https://notebook.example.com"
      }
    }
  }
}

Over HTTP. For clients that connect to a URL instead of launching a process:

knowledge-bundle-mcp --transport http --port 8765

It serves streamable HTTP at http://127.0.0.1:8765/mcp. It listens only on your own machine by default. Put authentication in front of it before exposing it anywhere else.

Tools

Every tool returns structured data with a published schema, so an assistant can work with the results instead of parsing text. Errors always look like knowledge.<module>.<code>: <message> Fix: <hint>.

Safety

• Knowledge only calls the Open Notebook server you configure. It sends nothing anywhere else and keeps no data of its own.
• open_notebook_note_create changes your notes, so you approve each one. When the assistant asks to save, Knowledge asks you directly through your MCP client (MCP elicitation) and shows the notebook, title and full text. The assistant can't answer that question for you.
• Some MCP clients can't ask you questions yet. In those, Knowledge refuses to write unless you've pre-approved the notebook with KNOWLEDGE_OPEN_NOTEBOOK_ALLOWED_NOTEBOOKS, or turned approval off with KNOWLEDGE_OPEN_NOTEBOOK_REQUIRE_CONFIRM=false.
• Before anything is written, text that looks like a credential (API keys, tokens, private keys, passwords in URLs) is refused. The error names the kind of credential found, never the value.
• Use an https:// address for your server, and give the password only to Knowledge, not to other tools.

Develop

uv venv && uv pip install -e '.[dev]'
.venv/bin/pytest

License

MIT. Published by Seaynic Labs.