Lets an AI assistant search, read, and write notes in a self-hosted Open Notebook knowledge base using specialized skills.
Also known as seayniclabs/knowledge, knowledge-bundle-mcp
- Stars
- 0
- Tools
- 8
- Downloads, 30 days
- 559
- Latest version
- 0.2.1
- Last commit
- Nov 3, 2026
- License
- MIT
What is Knowledge MCP?
Knowledge lets an AI assistant search, read, and write notes in a self-hosted Open Notebook knowledge base using specialized skills. It exposes 8 tools, such as open_notebook_notebooks, open_notebook_search, open_notebook_notes.
Summary generated from the project's README
About Knowledge MCP server
Managing a personal knowledge base through an AI assistant is possible with this server, which connects to a self-hosted Open Notebook instance. It allows users to search, read, and write notes using specialized skills designed for structured tasks like meeting notes, decision records, and weekly reviews. The server acts as a bundle of tools and instructions that can be installed via uv or pip to work with clients like Claude Desktop, Cursor, or VS Code.
Users interact with their data locally or via a configured Open Notebook URL, providing necessary credentials through environment variables or a config file. To ensure security, the system requires manual approval for creating notes or adding sources, including local files. It includes specific modules for research-with-sources and obsidian-markdown, allowing the assistant to cite claims and use wikilinks. The setup is designed so that updates only change assistant capabilities when you choose to enable new modules.
What you can do with it
- 1Conduct source-backed researchAsk your assistant to answer questions using your notebooks while citing specific claims and flagging disagreements.
- 2Generate structured meeting notesHave the AI transform a conversation into a Markdown file and save it directly to a notebook.
- 3Maintain architecture decision recordsInstruct the assistant to create a numbered Architecture Decision Record within a specific folder.
- 4Perform weekly knowledge reviewsRequest a summary of all items that were completed, left open, or planned for next week based on recent note changes.
Written from the project's README. Every use case is checked against a quote from it.
How to install Knowledge MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Knowledge MCP in Claude Code
$ claude mcp add --env 'KNOWLEDGE_OPEN_NOTEBOOK_PASSWORD=<YOUR_KNOWLEDGE_OPEN_NOTEBOOK_PASSWORD>' knowledge -- uvx knowledge-bundle-mcpInstall Knowledge MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"knowledge": {
"command": "uvx",
"args": [
"knowledge-bundle-mcp"
],
"env": {
"KNOWLEDGE_OPEN_NOTEBOOK_PASSWORD": "<YOUR_KNOWLEDGE_OPEN_NOTEBOOK_PASSWORD>"
}
}
}
}Install Knowledge MCP in VS Code
.vscode/mcp.json
{
"servers": {
"knowledge": {
"type": "stdio",
"command": "uvx",
"args": [
"knowledge-bundle-mcp"
],
"env": {
"KNOWLEDGE_OPEN_NOTEBOOK_PASSWORD": "<YOUR_KNOWLEDGE_OPEN_NOTEBOOK_PASSWORD>"
}
}
}
}Install Knowledge MCP in VS Code CLI
$ code --add-mcp '{"name":"knowledge","type":"stdio","command":"uvx","args":["knowledge-bundle-mcp"],"env":{"KNOWLEDGE_OPEN_NOTEBOOK_PASSWORD":"<YOUR_KNOWLEDGE_OPEN_NOTEBOOK_PASSWORD>"}}'Install Knowledge MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"knowledge": {
"command": "uvx",
"args": [
"knowledge-bundle-mcp"
],
"env": {
"KNOWLEDGE_OPEN_NOTEBOOK_PASSWORD": "<YOUR_KNOWLEDGE_OPEN_NOTEBOOK_PASSWORD>"
}
}
}
}Install Knowledge MCP in Codex
$ codex mcp add knowledge --env 'KNOWLEDGE_OPEN_NOTEBOOK_PASSWORD=<YOUR_KNOWLEDGE_OPEN_NOTEBOOK_PASSWORD>' -- uvx knowledge-bundle-mcpInstall Knowledge MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.knowledge] command = "uvx" args = ["knowledge-bundle-mcp"] [mcp_servers.knowledge.env] KNOWLEDGE_OPEN_NOTEBOOK_PASSWORD = "<YOUR_KNOWLEDGE_OPEN_NOTEBOOK_PASSWORD>"
Install Knowledge MCP in Gemini CLI
$ gemini mcp add -s user -e 'KNOWLEDGE_OPEN_NOTEBOOK_PASSWORD=<YOUR_KNOWLEDGE_OPEN_NOTEBOOK_PASSWORD>' knowledge uvx -- knowledge-bundle-mcpInstall Knowledge MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"knowledge": {
"command": "uvx",
"args": [
"knowledge-bundle-mcp"
],
"env": {
"KNOWLEDGE_OPEN_NOTEBOOK_PASSWORD": "<YOUR_KNOWLEDGE_OPEN_NOTEBOOK_PASSWORD>"
}
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for knowledge-bundle-mcp 0.2.1 in an isolated container with no network and no keys. It answered and listed 8 tools.
Knowledge MCP tools 8
Read from the server with tools/listopen_notebook_notebooksRead-onlyList your notebooks, most recently updated first. Page with offset=<next_offset>.
open_notebook_searchRead-onlySearch sources and notes. mode 'text' matches keywords; 'vector' matches meaning and needs an embedding model set up on the server. Limit a search to one notebook with notebook_id. Page with offset=<next_offset>.
open_notebook_notesRead-onlyList the notes in one notebook, titles only. Read a note with open_notebook_note_get. Page with offset=<next_offset>.
open_notebook_note_getRead-onlyRead one note. Long content is cut at max_chars (up to 50000) and marked truncated.
open_notebook_source_getRead-onlyRead one source: its title, topics, extracted text (cut at max_chars, up to 50000) and the notebooks it belongs to.
open_notebook_note_createActionCreate a note in a notebook. Without confirm=true it only returns a preview. With confirm=true you are asked to approve it (unless the notebook is pre-approved in settings); the assistant cannot approve on your behalf. Text that looks like a credential is refused.
open_notebook_add_sourceActionAdd a web link or a local file as a source in one notebook. Give exactly one of url or file_path. Without confirm=true it only returns a preview. With confirm=true you are asked to approve it; the assistant cannot approve for you. A local file is always approved by you, with its full path and size shown, and is never pre-approved in settings. Open Notebook processes the source in the background: check progress with open_notebook_source_get.
knowledge_modulesRead-onlyWhich modules are on, what settings are missing, and what each tool does. Pass a module name for its full settings list.
Configuration
KNOWLEDGE_OPEN_NOTEBOOK_PASSWORDSecretPassword for your Open Notebook server, if it has one
KNOWLEDGE_OPEN_NOTEBOOK_ALLOWED_NOTEBOOKSComma-separated notebook names the assistant may write to without asking
KNOWLEDGE_OPEN_NOTEBOOK_REQUIRE_CONFIRMtrue (default): you approve each new note. false: the assistant may write on its own
KNOWLEDGE_OPEN_NOTEBOOK_URLAddress of your Open Notebook server, e.g. https://notebook.example.com
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableseayniclabs/knowledge is public and reachablegithub.com/seayniclabs/knowledge ↗Pass
- Package names this repository as its sourceknowledge-bundle-mcp names seayniclabs/knowledge as sourcepypi.org/project/knowledge-bundle-mcp/ ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for knowledge-bundle-mcppypi.org/project/knowledge-bundle-mcp/ ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-03github.com/seayniclabs/knowledge ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from knowledge-bundle-mcpPass
- No critical advisory in the package or its dependencies37 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model8 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubKnowledge
Made by Seaynic Labs. Need tools like this built around your own systems? We do that.
Knowledge lets an AI assistant search, read and write the notes in your self-hosted Open Notebook, and comes with skills that teach it to do that work well: meeting notes, decision records, weekly reviews and source-backed research.
It is a bundle: tools, skills and instructions in one install. The tools are 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.
| Security card | |
|---|---|
| Network | Only the Open Notebook server you configure (KNOWLEDGE_OPEN_NOTEBOOK_URL). Open Notebook fetches the links you add, not Knowledge. Nothing else, no telemetry. |
| Files | Reads its config file ( |
| Secrets | API keys and passwords come from your environment or config file. They are never tool arguments and never returned to the model. |
| Read-only tools | 6: open_notebook_notebooks, open_notebook_search, open_notebook_notes, open_notebook_note_get, open_notebook_source_get, knowledge_modules |
| Needs your approval | open_notebook_note_create, open_notebook_add_source: you approve each write in your app, or pre-approve notebooks in settings (not for local files). The AI cannot approve for you. |
| Startup cost | about 4,600 tokens (8 tools, 7 skill prompts) |
| Changes | Tool descriptions are locked by hash (tool-manifest.lock.json); CI fails if they change silently. |
Skills
| Skill | What it does | Source |
|---|---|---|
getting-started |
Checks the settings, runs the first calls, explains approvals and errors | Seaynic Labs (MIT) |
research-with-sources |
Answers from your notebooks, cites each claim, flags sources that disagree | Seaynic Labs (MIT) |
weekly-review |
Done, open and next-week items from the notes you changed this week | Seaynic Labs (MIT) |
meeting-notes |
Structured meeting notes as a Markdown file, optionally saved to a notebook | Seaynic Labs (MIT) |
decision-record |
A numbered Architecture Decision Record in a Decisions/ folder |
Seaynic Labs (MIT) |
icm-architect |
Organises a knowledge base as a folder structure that agents can walk | Jake Van Clief (MIT), credits |
obsidian-markdown |
Obsidian-flavoured Markdown: wikilinks, callouts, properties | Steph Ango (MIT), credits |
Skills reach every app. Claude Code and other skill-aware apps read the skills/ folder. Any MCP app gets the same text as prompts: getting-started, for example, is the prompt named getting-started. Third-party skills keep their own license files. See CREDITS.md.
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
Pinned install. For a fixed setup, pin the exact version. The plugin manifest pins it the same way:
uvx knowledge-bundle-mcp==0.2.1 --version
As a Claude Code plugin. One install gives you the MCP server and the skills. This needs the seayniclabs/plugins marketplace, which is published with the release:
/plugin marketplace add seayniclabs/plugins
/plugin install knowledge@seayniclabs
The plugin still needs your Open Notebook address in its settings. The plugin file is .claude-plugin/plugin.json.
First five minutes
-
Set
KNOWLEDGE_OPEN_NOTEBOOK_URLto your server's address (step 2 below shows where). -
Run the check. It prints
okorFIXfor each item and exits 0 when everything is ready:knowledge-bundle-mcp --doctor -
Start your assistant and ask it to list your notebooks. It calls
open_notebook_notebooksand shows you the names. -
Ask it to search a word you know is in one of your notes. It calls
open_notebook_search. -
Ask it to save a note. It shows a preview first, then asks you to approve the save in your app.
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.
| Variable | Module | What it is |
|---|---|---|
KNOWLEDGE_OPEN_NOTEBOOK_URL |
open_notebook | Address of your Open Notebook server, e.g. https://notebook.example.com. No path. |
KNOWLEDGE_OPEN_NOTEBOOK_PASSWORD |
open_notebook | Only if your server has a password (OPEN_NOTEBOOK_PASSWORD on the server). Leave it unset otherwise. |
KNOWLEDGE_OPEN_NOTEBOOK_REQUIRE_CONFIRM |
open_notebook | true by default: you approve each new note and link. false lets the assistant save them on its own. Local files always need your approval. |
KNOWLEDGE_OPEN_NOTEBOOK_ALLOWED_NOTEBOOKS |
open_notebook | Optional. Comma-separated notebook names the assistant may save links and notes to without asking, e.g. Research,Inbox |
KNOWLEDGE_APPROVAL_LOG |
any | Optional. Where the approval log is written. Default: ~/.local/state/knowledge/approvals.jsonl |
KNOWLEDGE_<MODULE>_ENABLED |
any | false turns a module off, e.g. KNOWLEDGE_OPEN_NOTEBOOK_ENABLED=false |
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"
}
}
}
}
| Client | Where the config goes |
|---|---|
| Claude Desktop | claude_desktop_config.json (Settings → Developer → Edit Config) |
| Claude Code | claude mcp add knowledge -- uvx knowledge-bundle-mcp, then add the env values, or a project .mcp.json |
| Cursor | ~/.cursor/mcp.json, or .cursor/mcp.json in a project |
| VS Code | .vscode/mcp.json, using "servers" instead of "mcpServers" |
| Sonique, Hermes, OpenClaw, others | Any client that launches a stdio MCP server: command uvx, args ["knowledge-bundle-mcp"], plus the env values |
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.
Try these
Paste any of these into your assistant once Knowledge passes --doctor:
- "List my notebooks and tell me which one changed most recently."
- "Search my notebooks for what I wrote about the Q3 budget, and cite each note."
- "Write a weekly review of the notes I changed this week, using the weekly-review skill."
- "Make an ADR for choosing SQLite over Postgres for the prototype, with the alternatives table filled in."
- "Save this link to my Research notebook: https://example.com/article. Show me the preview first."
Tools
| Tool | What it returns |
|---|---|
knowledge_modules |
Which modules are on, which settings are missing, the skills, and the publisher. Call this first. |
open_notebook_notebooks |
Your notebooks, most recently updated first, paged |
open_notebook_search |
Matching sources and notes. mode is text (keywords) or vector (meaning; needs an embedding model on the server). Optional notebook_id. Paged. |
open_notebook_notes |
The notes in one notebook, titles only, paged |
open_notebook_note_get |
One note's content, cut at max_chars |
open_notebook_source_get |
One source: title, topics, extracted text, notebooks, processing status |
open_notebook_note_create |
Saves a note after you approve it. Without confirm=true it only returns a preview. |
open_notebook_add_source |
Adds a web link, or a local file you name, as a source. Preview first; you approve it. Processed in the background. |
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_createandopen_notebook_add_sourcechange your notebooks, 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, the title and the full text or link. The assistant can't answer that question for you.- A local file is read only after you name it, and it is uploaded only after you approve its full path and size. Files named like credential stores (
.env,.netrc, private keys,*.pem,*.key) and files in~/.ssh,~/.awsor~/.gnupgare refused. - 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 withKNOWLEDGE_OPEN_NOTEBOOK_REQUIRE_CONFIRM=false. Local files are never pre-approved. - Before anything is written or sent, 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
python3 scripts/check_skills.py
.venv/bin/python scripts/tool_lock.py --check
.venv/bin/python scripts/security_card.py --check
scripts/tool_lock.py (without --check) rewrites tool-manifest.lock.json after a deliberate change to a tool, prompt or instruction. Add a changelog line in the same commit.
Security
Report a vulnerability privately through GitHub (Security tab, "Report a vulnerability"). See SECURITY.md. Every approval, decline and refusal is logged locally in ~/.local/state/knowledge/approvals.jsonl: titles, notebook names and sizes, never the text. Set KNOWLEDGE_APPROVAL_LOG to move it.
License
MIT. Published by Seaynic Labs. Third-party skills are credited in CREDITS.md and keep their own licenses.
Built by Seaynic Labs. We build tools like this around a business's own systems: local-first, with a person approving every change. See custom integrations.
Knowledge MCP questions
How do I add Knowledge MCP to Claude Code?
Run claude mcp add --env 'KNOWLEDGE_OPEN_NOTEBOOK_PASSWORD=<YOUR_KNOWLEDGE_OPEN_NOTEBOOK_PASSWORD>' knowledge -- uvx knowledge-bundle-mcp in your terminal. Add --scope user to make it available in every project.
How do I add Knowledge MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Knowledge MCP provide?
It exposes 8 tools, including open_notebook_notebooks, open_notebook_search, open_notebook_notes, open_notebook_note_get, open_notebook_source_get.
What can the Knowledge server do with my notes?
It allows an AI assistant to search, read, and write notes in your self-hosted Open Notebook, including specialized tasks like meeting notes and research.
Does the server send my data to third parties?
No, it only connects to the Open Notebook server you configure and does not use telemetry.