nb-mcp-server

nb-mcp

MCP server wrapping the nb CLI for LLM-friendly note-taking.

Motivation

Using nb directly via shell has two problems for LLM assistants:

1. Backtick escaping: Markdown content with backticks triggers shell command substitution, corrupting notes.

1. Notebook context: nb assumes a default notebook, making per-project use awkward.

This MCP server solves both by:

• Accepting content as JSON parameters (no shell escaping needed)
• Qualifying all commands with an explicit notebook

Quick Start

Prerequisites

Install nb by following the official instructions: nb installation guide.

Installation

From crates.io:

cargo install nb-mcp-server

See the changelog for release history and upgrade notes.

Or download a prebuilt binary from GitHub Releases.

Build from Source

cargo build --release

Run

With default notebook from environment:

NB_MCP_NOTEBOOK=myproject ./target/release/nb-mcp

Or via CLI argument (takes precedence):

./target/release/nb-mcp --notebook myproject

Disable commit and tag signing in the notebook repository:

./target/release/nb-mcp --notebook myproject --no-commit-signing

Allow new notes at the notebook root instead of requiring a folder:

./target/release/nb-mcp --notebook myproject --allow-top-level-notes

Print the installed version:

./target/release/nb-mcp --version

Show the resolved notebook path and state directory:

./target/release/nb-mcp --show-paths

MCP Configuration

Add to your MCP client configuration (e.g., .mcp.json):

{

"mcpServers": { "nb": { "command": "/path/to/nb-mcp", "args": ["--notebook", "myproject"] } } }

Commands

The canonical access path is the multiplexed nb tool with a command parameter, which reduces the token footprint of the MCP server. The args field must be a JSON object. Stringified JSON payloads are rejected. Unknown args fields are rejected instead of ignored; use the exact command schema fields or documented aliases. Returned identifiers such as coordination/mcp/1 or myproject:coordination/mcp/1 are nb selectors, not filesystem paths in the current repository. Notebook storage is managed by nb configuration. The notebook argument must be a bare notebook name. Use folder for folder paths and id / selector for note selectors. Existing-item commands accept copied selectors such as myproject:coordination/mcp/1, but reject conflicts with a separate notebook argument.

First-Class Tools

All commands are also available as direct first-class tools with typed schemas: add, show, delete, move, list, search, todo, do, undo, tasks, bookmark, folders, mkdir, import, status, notebooks, plus the body-aware tools replace_note_body, edit_note_substring, edit_note_lines, retitle_note, edit_note_tags, and the line tools show_note_lines, search_note_lines. These bypass the multiplexed command dispatch. The multiplexed nb tool remains as the compact/backcompat compatibility surface for the retained commands.

Notes

Todos

Organization

Examples

Create a note with code:

{

"command": "nb.add", "args": { "title": "API Design Notes", "content": "# API Design\n\nUse GET /items for listing.\n\npython\nresponse = client.get('/items')\n", "tags": ["design", "api"], "folder": "docs" } }

Search for notes:

{

"command": "nb.search", "args": { "queries": ["API", "design"], "mode": "any", "tags": ["design"] } }

Tagging Suggestions

For multi-LLM projects, consider using consistent tag prefixes (optional). Example categories and prefixes:

Body-Aware Editing

The legacy nb.edit tool (and its overwrite/append/prepend modes) was removed in the nb-api 0.3 cutover. The body-aware replacement tools are direct-only (no multiplexed nb.* aliases) and are designed to prevent the destructive whole-note-overwrite failure mode that the old surface enabled:

• replace_note_body — replace the entire note body with plain UTF-8 new_body. Requires the body fingerprint from a preceding show; a stale fingerprint is rejected with re-read guidance so you cannot overwrite a note you have not just read.
• edit_note_substring — replace one or more occurrences of a plain-text pattern with replacement. expected_count must match the actual match count; an optional fingerprint guards against stale edits.
• edit_note_lines — apply a batch of disjoint insert/delete/replace edits verified against line anchors from one original snapshot; content is bare text (no terminator bytes; the library appends the document EOL, so single-line replaces never merge the next line).
• retitle_note — change the title without changing the path.
• edit_note_tags — add and/or remove tags in one atomic operation.

These tools address notes by a flat id (alias selector) string exactly like show/delete/move; notebook-relative filenames are not exposed, and qualified selectors returned by show/show_note_lines/ search_note_lines round-trip directly as id. Since nb-api 0.4, numeric .index ids are surfaced too: reads and mutation outcomes carry selector plus numeric_id, and / / are accepted as id (ids are folder-local, positional, and never reused; path stays canonical). Body content (pattern, replacement, title, new_body, line-edit content) and line/search text/title are native UTF-8 strings with no base64 anywhere on the wire. Line-level reads are available through show_note_lines (bounded, anchored windows with a document-level eol declaration — lf/crlf plus has_final_eol — instead of per-line terminators) and search_note_lines (anchored matches, no EOL fields by design), which support search-to-edit without reading the whole note. New notes get nb-faithful filenames mangled from the title (Hello World Title → hello_world_title.md).

add creates notes only: todo-shaped content (checkbox lines or a Tasks heading outside fenced code blocks) is rejected with a hint to use the todo tool instead.

Invoking multiplexed nb.edit is rejected with recovery guidance naming the replacement tools. The body-aware and line tools are direct-only: invoking them through the multiplexed nb tool is rejected.

Structured Results

• show returns a text-first slim structured envelope: selector, path, kind, todo_state, title (normalized Option ), tags, body (full UTF-8 text), body_contiguous, fingerprint, and numeric_id. No base64 field is exposed. When the source is not valid UTF-8, show returns a typed NonUtf8 error carrying the MIME hint plus guidance to an external raw-retrieval facility outside MCP (the nb CLI); a non-textual target returns UnsupportedShowTarget. Neither ever returns base64 bytes.
• Mutating tools (add, todo, bookmark, mkdir, delete, move, do, undo, and the body-aware tools) return a structured CommitOutcome: commit_created, revision_id, pre_revision, and per-operation path/selector/numeric_id/noop/fingerprint. Idempotent no-op mutations report commit_created: false.

Typed Error Surfaces

nb-api 0.4 introduces typed failures that the MCP layer translates into actionable diagnostics on both the multiplexed nb.* surface and the first-class tool surface. NonUtf8 and IndexLockTimeout (busy .index lock; retry later, nothing mutated) join the existing set:

• show on a non-text selector (folder, archive, image, ...): the error names the selector and the actual non-text type, states that show reads text notes only, and points the caller at folders/list. The server never silently re-routes show to another command.
• add with both a title and a content whose first nonblank line is an H1 that duplicates the title: the error names the title and the detected heading and tells the caller to remove the duplicate H1 or omit the separate title.
• Stale-editing guards: FingerprintMismatch, AnchorMismatch, and OccurrenceMismatch tell the caller to re-read the note and retry with fresh fingerprint/anchors/counts.
• FragmentedBody: a multi-fragment body (for example a bookmark with multiple body fragments) refuses line/substring/body-replace operations; metadata operations (retitle_note, edit_note_tags) still apply.
• DirtyBaseline: a mutation refuses when the notebook worktree/index is dirty; the diagnostic tells the caller to commit or clean it first.
• IndeterminateCommit / RecoveryRequired: commit completion is unknown or recovery is needed; the diagnostic instructs the caller not to auto-retry and to inspect HEAD/status before acting.
• GateTimeout: the notebook is busy; retry later.
• PathCollision / PathIgnored / UnsupportedStructure / PlanValidation: surface the specific path/plan guidance.

Configuration

Notebook Resolution

Priority order:

1. Per-command notebook argument (highest)
2. CLI --notebook flag
3. NB_MCP_NOTEBOOK environment variable
4. Git-derived default from the master worktree path

If no notebook can be resolved, commands fail with a configuration error. The server does not fall back to nb's default notebook.

If the resolved notebook does not exist, the server creates it automatically. Use --no-create-notebook to disable automatic creation.

Logging

Logs are written to ~/.local/state/nb-mcp/{project}--{worktree}.log (XDG-compliant).

For Git worktrees, logs are named after both the master project and the worktree basename to avoid collisions between multiple MCP server instances.

Use --show-paths to print the resolved notebook path and