Open Notebook MCP Server

An MCP (Model Context Protocol) server that provides tools to interact with the Open Notebook API. This server enables AI assistants like Claude to manage notebooks, sources, notes, search content, and interact with AI models through Open Notebook.

Features

• Notebooks Management: Create, read, update, and delete notebooks
• Sources Management: Add and manage content sources (links, uploads, text)
• Notes Management: Create and organize notes within notebooks
• Search & AI: Search content using vector/text search and ask questions
• Models Management: Configure and manage AI models
• Chat Sessions: Create and manage chat conversations
• Settings: Access and update application settings
• Progressive Disclosure: Efficient tool discovery with search_capabilities

Installation

Using uv (recommended)

# Clone the repository
git clone https://github.com/PiotrAleksander/open-notebook-mcp.git
cd open-notebook-mcp

# Install with uv
uv sync

Using pip

pip install -e .

Configuration

The server requires configuration to connect to your Open Notebook instance:

Environment Variables

Create a .env file or set these environment variables:

# Required: URL of your Open Notebook instance
OPEN_NOTEBOOK_URL=http://localhost:5055

# Optional: Authentication password (if APP_PASSWORD is set in Open Notebook)
OPEN_NOTEBOOK_PASSWORD=your_password_here

# Optional: Transport configuration (default: stdio)
MCP_TRANSPORT=stdio  # or streamable-http for remote deployment

Example Configuration

For local development with default Open Notebook settings:

# .env
OPEN_NOTEBOOK_URL=http://localhost:5055

If you've configured authentication in Open Notebook:

# .env
OPEN_NOTEBOOK_URL=http://localhost:5055
OPEN_NOTEBOOK_PASSWORD=my_secure_password

Usage

Running the Server

Development Mode (STDIO)

For local use with AI assistants:

uv run open-notebook-mcp

Or using the MCP CLI:

mcp dev src/open_notebook_mcp/server.py

Production Mode (Streamable HTTP)

For remote deployment:

MCP_TRANSPORT=streamable-http HOST=0.0.0.0 PORT=8000 uv run open-notebook-mcp

Using with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "open-notebook": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/open-notebook-mcp",
        "open-notebook-mcp"
      ],
      "env": {
        "OPEN_NOTEBOOK_URL": "http://localhost:5055",
        "OPEN_NOTEBOOK_PASSWORD": "your_password_if_needed"
      }
    }
  }
}

Discovering Available Tools

The server implements progressive disclosure. Use the search_capabilities tool to discover available functionality:

# Get a summary of all tools
search_capabilities(query="", detail="summary", limit=50)

# Search for specific functionality
search_capabilities(query="notebook", detail="summary", limit=10)

# Get full details for a specific tool
search_capabilities(query="create_notebook", detail="full", limit=1)

Example Workflows

Creating and Managing Notebooks

# Create a new notebook
result = create_notebook(
    name="AI Research",
    description="Research on AI applications"
)
notebook_id = result["notebook"]["id"]

# List all notebooks
notebooks = list_notebooks(archived=False, limit=20)

# Update a notebook
update_notebook(
    notebook_id=notebook_id,
    name="AI Research (Updated)"
)

# Get a specific notebook
notebook = get_notebook(notebook_id=notebook_id)

Adding Sources

# Add a web source
source = create_source(
    notebook_id=notebook_id,
    type="link",
    url="https://example.com/ai-article",
   

... [View full README on GitHub](https://github.com/Epochal-dev/open-notebook-mcp#readme)