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.

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\n```python\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:

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 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:

• Contribution guide
• Code of conduct

License

Apache 2.0