Metadata-Version: 2.4
Name: bangbangmao-open-notebook-mcp
Version: 0.2.1
Summary: MCP (Model Context Protocol) server for Open Notebook — access research notebooks, sources, notes and search via any MCP client (Claude Desktop, VS Code, etc.)
Author: bangbangmao
License-Expression: MIT
Project-URL: Homepage, https://github.com/lfnovo/open-notebook
Project-URL: Repository, https://github.com/lfnovo/open-notebook
Project-URL: Documentation, https://open-notebook.ai
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: mcp[cli]>=1.6.0
Requires-Dist: httpx>=0.27.0

# Open Notebook MCP Server

A lightweight [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server for [Open Notebook](https://open-notebook.ai) — access research notebooks, sources, notes, and semantic search from any MCP-compatible client (Claude Desktop, VS Code, Cline, etc.).

## Architecture

This server runs in **HTTP proxy mode**: it proxies every request through Open Notebook's existing REST API. That means:

- **Zero database dependencies** — no SurrealDB connection needed
- **Minimal install** — only depends on `mcp` and `httpx`
- **Side-by-side with the web UI** — just point it at the API

## Installation

```bash
uv tool install open-notebook-mcp
```

Or run without installing:

```bash
uvx open-notebook-mcp
```

After installation, the `open-notebook-mcp` command is available globally.

## Configuration

The server needs to know where your Open Notebook API is running:

| Environment Variable | Default | Description |
|---|---|---|
| `OPEN_NOTEBOOK_URL` | `http://localhost:5055` | Open Notebook API base URL |
| `OPEN_NOTEBOOK_PASSWORD` | — | API password (if authentication is enabled) |
| `OPEN_NOTEBOOK_MCP_PORT` | `0` (stdio) | Set to a port number to run SSE transport instead of stdio |

## Usage

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "open-notebook": {
      "command": "open-notebook-mcp",
      "env": {
        "OPEN_NOTEBOOK_URL": "http://localhost:5055",
        "OPEN_NOTEBOOK_PASSWORD": "your-password"
      }
    }
  }
}
```

### VS Code

Add to your `.vscode/mcp.json`:

```json
{
  "servers": {
    "open-notebook": {
      "command": "open-notebook-mcp",
      "env": {
        "OPEN_NOTEBOOK_URL": "http://localhost:5055",
        "OPEN_NOTEBOOK_PASSWORD": "your-password"
      }
    }
  }
}
```

## Available Tools

| Tool | Description |
|---|---|
| `list_notebooks` | List all notebooks with source and note counts |
| `get_notebook` | Get detailed information about a specific notebook |
| `get_notebook_context` | Build full notebook context as plain text |
| `list_sources` | List sources in a notebook with titles and previews |
| `get_source` | Get full source details including insights |
| `list_notes` | List notes in a notebook |
| `search` | Full-text or vector search across all notebooks |
| `list_source_chat_sessions` | List all chat sessions for a source |
| `get_source_chat_session` | Get a chat session's full conversation with messages |

## Development

```bash
cd mcp-server
uv run open-notebook-mcp
```

## Publishing

```bash
cd mcp-server
uv build
uv publish
```

## License

MIT
