# claude-nb-mcp

MCP server for integrating [nb](https://github.com/xwmx/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](https://github.com/xwmx/nb) (v7.x recommended)
- Node.js >= 18.0.0
- Claude Code

### Installing nb

```bash
# 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:

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

2. Install dependencies:

```bash
npm install
```

3. Build the project:

```bash
npm run build
```

4. Register with Claude Code:

```bash
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:**
```typescript
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:**
```typescript
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:**
```typescript
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:**
```typescript
nb_show({ id: 3 })
```

### Custom Notebook Name

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

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

## Development

```bash
# 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:
```bash
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:
```bash
nb notebooks
```

Verify the notebook name matches your project directory:
```bash
nb dotfiles:list  # Replace 'dotfiles' with your directory name
```

### Permission errors

Ensure the MCP server has execute permissions on `nb`:
```bash
which nb
nb --version
```

## License

MIT

## Contributing

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