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:

Backtick escaping: Markdown content with backticks triggers shell command substitution, corrupting notes.
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.

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	`query`, `tags[]`

Todos

Command	Description	Key Arguments
`nb.todo`	Create a todo	`description`, 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"],
    "folder": "docs"
  }
}

Search for notes:

{
  "command": "nb.search",
  "args": {
    "query": "API",
    "tags": ["design"]
  }
}

Tagging Suggestions

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

Category	Pattern	Examples
Collaborator	`llm-<name>`	`llm-claude`, `llm-gpt`
Component	`component-<name>`	`component-api`, `component-ui`
Task type	`task-<type>`	`task-bug`, `task-feature`
Status	`status-<state>`	`status-review`, `status-blocked`

Configuration

Notebook Resolution

Priority order:

Per-command notebook argument (highest)
CLI --notebook flag
NB_MCP_NOTEBOOK environment variable
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 state directory.

Control log level with RUST_LOG:

RUST_LOG=debug nb-mcp --notebook myproject

Commit Signing

Use --no-commit-signing to disable commit and tag signing in the notebook repository. The server updates the notebook repository's local Git config so signing prompts do not block MCP tool calls.

Contributing

See the contribution guide and code of conduct:

License

Apache 2.0

nb-mcp-server 0.8.0