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

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

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

All commands are accessed via the nb tool with a command parameter to reduce the token footprint of the MCP server. The args field must be a JSON object. Stringified JSON payloads are rejected. 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.

Notes

Command	Description	Key Arguments
nb.add	Create a note	title, content, tags[], folder
nb.show	Read a note	id (alias: selector)
nb.edit	Update a note	id (alias: selector), content, mode (replace default, append, prepend)
nb.delete	Delete a note	id (alias: selector)
nb.move	Move or rename a note	id (alias: selector), destination
nb.list	List notes	folder, tags[], limit ([ ] / [x] indicate todo status; leading glyphs are item markers)
nb.search	Full-text search	queries[] (required), mode (any default, all), tags[]

Todos

Command	Description	Key Arguments
nb.todo	Create a todo	title, optional description (alias: content), optional tasks[], tags[]
nb.do	Mark complete	id (alias: selector), optional task_number
nb.undo	Reopen	id (alias: selector), optional task_number
nb.tasks	List todos	optional status (open or closed), optional recursive (true default)

Organization

Command	Description	Key Arguments
nb.bookmark	Save a URL	url, title, tags[], comment
nb.import	Import file/URL	source, folder, filename, convert
nb.folders	List folders	parent
nb.mkdir	Create folder	path
nb.notebooks	List notebooks only	(none)
nb.status	Notebook info	(none)

Examples

Create a note with code:

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

... [View full README on GitHub](https://github.com/emcd/nb-mcp-server#readme)