claude-nb-mcp

MCP server for integrating nb (command-line note-taking) with Claude Code.

Features

• Working Directory-based Notebooks: Automatically organizes notes by project/working directory
• Claude Folder Organization: Separates Claude-generated notes from manual notes
• 4 Core Tools: Add, list, search, and show notes
• Secure: Prevents command injection and provides proper error handling
• Easy Setup: Simple integration with Claude Code

Folder Structure

Claude-generated notes are automatically organized in a claude/ subfolder within each notebook:

~/.nb/
├── dotfiles/
│   ├── claude/              # Claude-generated notes
│   │   └── 20260101171752.md
│   └── manual-note.md       # Your manual notes
└── my-app/
    ├── claude/              # Claude-generated notes
    └── manual-note.md       # Your manual notes

This separation allows you to:

• Keep Claude's automatic notes separate from your manual notes
• Easily filter or search only Claude's notes
• Maintain a cleaner organization

Prerequisites

• nb (v7.x recommended)
• Node.js >= 18.0.0
• Claude Code

Installing nb

# macOS
brew install nb

# Or using the installer
curl -L https://raw.github.com/xwmx/nb/master/nb -o /usr/local/bin/nb && chmod +x /usr/local/bin/nb

Installation

1. Clone this repository:

cd ~/workspace  # or your preferred location
git clone https://github.com/lowbridgee/claude-nb-mcp.git
cd claude-nb-mcp

2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Register with Claude Code:

claude mcp add --transport stdio nb --scope user -- node /absolute/path/to/claude-nb-mcp/dist/index.js

Replace /absolute/path/to/claude-nb-mcp with the actual absolute path.

Usage

Automatic Notebook Selection

When you run Claude Code in a project directory, notes are automatically saved to a notebook named after that directory:

Working Directory	Notebook Name
/Users/you/dotfiles	dotfiles
/Users/you/projects/my-app	my-app

Available Tools

nb_add

Add a new note to the current project's notebook.

Parameters:

• content (required): Note content
• title (optional): Note title
• tags (optional): Array of tags

Example:

nb_add({
  content: "This is a technical note about the authentication bug.",
  title: "Auth Bug Analysis",
  tags: ["bug", "authentication"]
})

nb_list

List notes from the current project's notebook.

Parameters:

• limit (optional, default: 20): Maximum number of notes
• type (optional): Filter by type (note, bookmark, todo)

Example:

nb_list({ limit: 10, type: "note" })

nb_search

Search notes in the current project's notebook.

Parameters:

• query (required): Search query
• limit (optional, default: 10): Maximum results

Example:

nb_search({ query: "authentication", limit: 5 })

nb_show

Show the full content of a specific note.

Parameters:

• id (required): Note ID (from nb_list output)

Example:

nb_show({ id: 3 })

Custom Notebook Name

You can override the automatic notebook name by setting the NB_NOTEBOOK environment variable:

{
  "mcpServers": {
    "nb": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/claude-nb-mcp/dist/index.js"],
      "env": {
        "NB_NOTEBOOK": "my-custom-notebook"
      }
    }
  }
}

Development

# Build
npm run build

# Watch mode
npm run dev

How It Works

1. Notebook Detection: On startup, the server reads PWD or process.cwd() to determine the working directory
2. Notebook Name: Uses the basename of the working directory (e.g., dotfiles from /Users/you/dotfiles)
3. nb Commands: Executes nb <notebook>:<command> for all operations

Troubleshooting

"nb command not found"

Install nb:

brew install nb
# or
curl -L https://raw.github.com/xwmx/nb/master/nb -o /usr/local/bin/nb && chmod +x /usr/local/bin/nb

Notes not showing up

Check which notebooks exist:

nb notebooks

Verify the notebook name matches your project directory:

nb dotfiles:list  # Replace 'dotfiles' with your directory name

Permission errors

Ensure the MCP server has execute permissions on nb:

which nb
nb --version

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.