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.

2. 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

| C

... View full README on GitHub