bangbangmao-open-notebook-mcp 0.2.0

MCP (Model Context Protocol) server for Open Notebook — access research notebooks, sources, notes and search via any MCP client (Claude Desktop, VS Code, etc.)

Open Notebook MCP Server

A lightweight MCP (Model Context Protocol) server for Open Notebook — 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

uv tool install open-notebook-mcp

Or run without installing:

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:

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

{
  "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

cd mcp-server
uv run open-notebook-mcp

Publishing

cd mcp-server
uv build
uv publish

License

MIT