Nb-mcp Server

You run an MCP server that wraps the nb command line interface to make per-project notebooks easier to use with large language models. It accepts content as JSON, avoids shell escaping issues, and always ties actions to a specific notebook so you can work on multiple projects cleanly.

How to use

To use this MCP server, run it locally and connect your MCP client to the server. You can start the server with a specific notebook, or let the server derive the notebook from a command line option or environment variable. Once running, your MCP client sends JSON commands that are forwarded to nb for creation, editing, or querying notes, todos, and organization tasks, all scoped to the chosen notebook.

How to install

Prerequisites: you need Rust tooling and the nb command line utility installed on your system.

Install the MCP server from crates.io or use a prebuilt binary if you prefer.

Install from crates.io:

Or download a prebuilt binary from the release assets and place it on your PATH.

If you want to build from source, use the release build:

Run with a default notebook derived from the environment or explicit CLI option. For example, you can set the notebook using an environment variable or pass it as an argument when starting the server.

Examples to start the server with a specific notebook:

Print the installed version and show runtime paths for debugging:

Configure your MCP client to use this server by adding a server entry that points to the MCP binary and its notebook argument. For example, in your client config you reference the MCP executable and specify the notebook to use.

Additional configuration and usage notes

Notebook resolution follows a priority that ensures the server uses the most explicit notebook you provide. If no notebook is resolvable, commands fail with a configuration error. When the resolved notebook does not exist, the server creates it automatically unless you disable creation.

Logging is written to a per-project log file in your home directory (XDG-compliant). For Git worktrees, logs are named to avoid collisions between multiple MCP server instances.

Control log verbosity with the RUST_LOG environment variable, for example to enable debug logs:

Configuration

Notebook resolution priority and behavior are as follows: per-command notebook argument, then the CLI --notebook flag, then NB_MCP_NOTEBOOK environment variable, then a Git-derived default from the master worktree path.

If the resolved notebook path does not exist, the server creates it automatically unless you specify otherwise with a flag to prevent automatic creation.

Commit signing can be disabled so commit and tag signing prompts do not block MCP tool calls: include the flag --no-commit-signing when starting the server.

Examples

Create a note with code and markdown content in the nb notebook via the MCP client.

Search for notes by query and tag using the MCP client.

Notes on configuration via MCP client

To enable consistent per-project work, configure your MCP client with a server entry that specifies the executable path and the notebook to use, ensuring the notebook is consistently applied to all commands.

Tagging suggestions

For multi-project setups, consider using a tagging scheme that helps organize notes by collaborator, component, task, and status. Examples include prefixes like llm-, component-, task-, and status- to group related notes and tasks.

Security and reliability notes

Keep the MCP server and its dependencies up to date. Use the local notebook directory and repository settings securely, and guard any environment variables containing sensitive project information.

Troubleshooting and tips

If commands fail due to notebook resolution, recheck the notebook argument, CLI flag, or environment variable you set for NB_MCP_NOTEBOOK. Use --show-paths to verify the resolved notebook path and state directory. Enable verbose logs with RUST_LOG to diagnose issues.

Contributing

Contribute by following the established contribution guidelines for the project and maintaining compatibility with the MCP protocol used by clients.

License

Apache 2.0 license applies to this MCP server.

Available tools

nb.add

Create a new note with a title, content, tags, and optional folder.

nb.show

Read a note by its identifier.

nb.edit

Update a note's content or metadata.

nb.delete

Delete a note, requiring explicit confirmation.

nb.list

List notes with optional filters like folder and tags.

nb.search

Full-text search across notes and metadata.

nb.todo

Create a new todo item with a description and optional tags.

nb.do

Mark a todo as completed by its id.

nb.undo

Reopen a completed todo by its id.

nb.tasks

List current todos.

nb.bookmark

Save a URL as a bookmark with optional title and tags.

nb.import

Import content from a file or URL into a notebook.

nb.folders

List folders within a notebook.

nb.mkdir

Create a new folder path within a notebook.

nb.notebooks

List available notebooks.

nb.status

Get information about the current notebook.