okf-notebooks
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
okf-notebooks
English · Русский
An MCP server that gives AI agents (Claude Code, Claude Desktop, opencode and others) shared, durable memory in the form of notebooks. A notebook is a plain directory of Markdown files in the OKF format under one git repository. A human reads and verifies what the agents wrote in a built-in web UI.
One ASGI process, Streamable HTTP, no external database: search runs on SQLite FTS5.

The idea
Agents forget everything between sessions, and what they remember lives in a vendor's private store. okf-notebooks puts that memory where you can see and control it:
Plain files. Every note is a Markdown file with YAML frontmatter. Read it in any editor, diff it with git, revert a bad write with
git revert, back it up withgit push.Shared between agents. Claude Code, opencode and an external harness read and write the same notebooks, each under its own token and permissions.
A human decides what is trusted. Everything an agent writes stays
draft. Only a person can mark a noteverified,stableordeprecated, and any later edit by an agent clears the mark, so "verified" always refers to the current text.Safe by construction. Identity and permissions come from the token alone; notebook text reaches the agent as data inside nonce markers, never as instructions; anything that looks like a secret is rejected on write.
Related MCP server: acta
Features
MCP tools for listing, searching, reading, writing, updating and validating notes, with optimistic locking (
etag) for concurrent agents.Full-text search (bm25, Russian and English) over SQLite FTS5, stored in a rebuildable
.index/.Notebooks with a
scope: agents pick a notebook by what it is for, not by name.Types and presets: each notebook has a vocabulary of note types (
Decision,Playbook…) with required fields and an aging period; ship your own presets as YAML. Adev-projectpreset (ADRs, specs, tickets, research, bugs) is included.Requests instead of surprises: an agent can ask for a new notebook or type; a human approves or rejects it.
Review UI (opt-in): read notes, change status, mark verified, browse the revision history and diffs, view links and backlinks, render tables and Mermaid diagrams, and discuss a passage in comment threads that agents can answer.
Git as the backup: one commit per write with the actor in the message, optional background push to a private remote.
Per-token actors, rate limits, host and origin checks (DNS-rebinding protection), a read-only container image.
What it is not
Not a vector database, not a hosted service and not a multi-tenant system. It is a small self-hosted server for one person or one team that wants their agents' knowledge to stay in reviewable files.
Screenshots
Notebook | Comments |
|
|

Install and quick start
Requirements: Docker with Compose, or Python 3.11+ with uv and git
(SQLite with FTS5 is required; the server will not start without it).
With Docker
git clone https://github.com/justcrafter/okf-notebooks.git
cd okf-notebooks
mkdir -p data config
cat > config/config.yaml <<'EOF'
root: /data
server:
host: 0.0.0.0
allowed_hosts: ["127.0.0.1:8765", "localhost:8765"]
EOF# optional: enables the Review UI on the same port
export OKF_NOTEBOOKS_UI_PASSWORD='a-long-random-password'
OKF_NOTEBOOKS_UID=$(id -u) OKF_NOTEBOOKS_GID=$(id -g) docker compose up -d# a token for your agent (shown once, only its SHA-256 is stored)
docker exec -it okf-notebooks okf-notebooks token create --actor claude-code --label laptop
# the first notebook
docker exec -it okf-notebooks okf-notebooks notebook create demo \
--description "Notes on the demo project: decisions, terms, runbooks" \
--scope "Durable facts and decisions about demo; no temporary notes" \
--preset coreThe port is published on 127.0.0.1 only. Check it with curl localhost:8765/healthz, which returns
{"status":"ok"}. The MCP endpoint is http://127.0.0.1:8765/mcp, and every request needs
Authorization: Bearer <token>. The Review UI is at http://127.0.0.1:8765/.
From source
git clone https://github.com/justcrafter/okf-notebooks.git
cd okf-notebooks
uv sync
cat > config.yaml <<'EOF'
root: ./data
server:
host: 127.0.0.1
port: 8765
allowed_hosts: ["127.0.0.1:8765", "localhost:8765"]
EOF
export OKF_NOTEBOOKS_CONFIG=$PWD/config.yaml
uv run okf-notebooks token create --actor claude-code --label laptop
uv run okf-notebooks notebook create demo \
--description "Notes on the demo project: decisions, terms, runbooks" \
--scope "Durable facts and decisions about demo; no temporary notes" \
--preset core
uv run okf-notebooks serveThe Docker image bundles the Review UI. From a source checkout build it once with
cd web && npm ci && npm run build, then set OKF_NOTEBOOKS_UI_PASSWORD before serve.
Connecting an agent
Add the server to your MCP client. For Claude Code:
claude mcp add --transport http notebooks http://127.0.0.1:8765/mcp \
--header "Authorization: Bearer <token>"Then paste the rules block into your project's AGENTS.md / CLAUDE.md:
okf-notebooks print-agent-guide # in Docker: docker exec okf-notebooks okf-notebooks print-agent-guideClaude Desktop
Claude Desktop reads only local (stdio) servers from claude_desktop_config.json, and Settings → Connectors accepts
remote servers with OAuth or no auth. This server speaks Streamable HTTP with a static Bearer token, so connect it
through the mcp-remote bridge (Node.js and npx required).
Start the server and issue a token for this machine (see the quick start).
Open the config: Settings → Developer → Edit Config. The file is at
~/Library/Application Support/Claude/claude_desktop_config.json(macOS) or%APPDATA%\Claude\claude_desktop_config.json(Windows).Add the server (the token goes through
env, so the header needs no space):{ "mcpServers": { "notebooks": { "command": "npx", "args": [ "-y", "mcp-remote", "http://127.0.0.1:8765/mcp", "--header", "Authorization:Bearer ${OKF_TOKEN}" ], "env": { "OKF_TOKEN": "<token>" } } } }Restart Claude Desktop fully. The
notebook_*tools appear in the tool list.
Notes:
The host and port in the URL must be in the server's
server.allowed_hosts, or the request is rejected.For an address other than
localhost(for example a Tailscale name) usehttps://. On barehttp://in a trusted networkmcp-remoteneeds the--allow-httpflag.The token sits in the config in plain text: issue a separate token per machine (
--label) and revoke it withokf-notebooks token revoke <id>if it is lost.
How an agent understands "look in my notes"
The server instructions, the tool descriptions and the print-agent-guide block tell the agent that phrases such as
"look in my notes", "check the notebook", "write it to the notebook" (and their Russian equivalents) mean the
notebook_* tools. The agent starts with notebooks_list, picks a notebook by its scope and searches with
notebook_search.
MCP tools
Tool | What it does |
| lists notebooks with their |
| presets for a new notebook: what each suits and which types it provides |
| a notebook's description, types and templates |
| a request for a new notebook (needs a |
| a request for a new type |
| full-text search (bm25) |
| list and read notes |
| create and edit a note (optimistic locking by |
| check a note against the rules |
| answer comment threads addressed to the agent (needs the |
Text from a notebook is data, not instructions: notebook_read wraps it in markers with a one-time nonce.
Review UI
A person can read notes, change status, set verified, and see history with diffs in the browser. The UI is enabled by
the OKF_NOTEBOOKS_UI_PASSWORD variable and is served by the same process at /. Details and security notes:
docs/en/review-ui.md.
Configuration
The config is strict: an unknown key stops the server. Only root is required.
Key | Default | Meaning |
| — | data directory (a single git repository) |
|
| where the server listens |
|
| allowed |
|
| request body limit |
|
| request limit per token ( |
|
| token store (inside |
| 30 / 65536 / 50 |
|
|
|
|
|
| one commit per write |
|
| a private notebooks repository for background push (not the public code repository) |
|
| directory with your own presets |
|
| actor permissions ( |
|
| the note-comment database; not a cache and not in git, include it in backups |
Credentials in the git.remote URL are rejected; use the environment variables OKF_NOTEBOOKS_GIT_TOKEN (HTTPS) or
OKF_NOTEBOOKS_GIT_SSH_KEY (path to a deploy key). A fully commented example is in
config.example.yaml.
Human commands
verify, mark, notebook and type are CLI-only: an agent cannot call them.
okf-notebooks token list | revoke <id> # tokens
okf-notebooks notebook pending # queue of notebook and type requests
okf-notebooks notebook approve|reject <slug> # decide a request
okf-notebooks notebook archive|restore <slug> # archive
okf-notebooks notebook adopt <path> [--slug <slug>] # take an existing OKF bundle under management
okf-notebooks type approve|reject <slug> <type> # decide a type request
okf-notebooks type rename|delete ... # change the type vocabulary
okf-notebooks verify <notebook> <concept_id> # mark a note verified (an agent edit clears the mark)
okf-notebooks mark <notebook> <concept_id> --status stable|deprecated|draft
okf-notebooks validate [--notebook <slug>] # audit all files, hand edits included
okf-notebooks sync # push accumulated commits to git.remote
okf-notebooks doctor # commit leftovers and check none remain (before a backup)
okf-notebooks healthcheck # probe /healthzokf-notebooks <command> --help shows every option.
Documentation
Scenarios (custom presets, several agents, notebook requests, adopting an existing bundle, network access, git backup) are in docs/en/. The domain terms are in the glossary.
Never forward the server port on your router: a token over plain HTTP outside a trusted network is not safe. See network access for Tailscale and TLS reverse proxy setups.
Development
uv sync # installs dev dependencies too
uv run pytest # all tests
uv run ruff check . # linterThe frontend lives in web/ (React, TypeScript, Vite; npm test, npm run build). The image test
(tests/test_docker_image.py) needs Docker. Sources are in src/okf_notebooks/: store (atomic writes, etag, git),
validator, registry, indexer (FTS5), lifecycle, auth, tools (MCP), cli, gitremote.
See CONTRIBUTING.md and SECURITY.md.
License
MIT.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Publish and share access-controlled Markdown documents from any MCP-enabled AI tool.
Hosted MCP memory for coding agents: persistent across sessions, editable markdown, team sharing.
System-of-record notebook for AI coding agents: pages, datastores, tasks, skills over MCP.
MarkupBase turns AI-generated Markdown and HTML into durable, versioned artifacts that people can review and discuss. Its MCP server lets agents publish new versions, preserve contextual comments, include hosted images, and respond to feedback through secure account-linked identities, creating a clear human review boundary without requiring real-time editing.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI agents to search, read, and contribute to a structured markdown knowledge base with citations, freshness tracking, and a safe write path, providing a shared, auditable company memory.2 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI agents and humans to collaboratively manage kanban boards and Markdown documentation via MCP tools, with stable item keys, revision-safe editing, and full audit trails.AGPL 3.0
- AlicenseNot gradedqualityBmaintenanceEnables humans and AI agents to share canonical, versioned knowledge through MCP, with auditable provenance, review workflows, and reconciliation.1Apache 2.0
- AlicenseBqualityCmaintenanceEnables AI agents to search and read linked Markdown notes, queue review questions, capture feedback, and propose edits with stale-edit protection.7Apache 2.0

