Open Notebook

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 repositorygit clone https://github.com/PiotrAleksander/open-notebook-mcp.gitcd open-notebook-mcp
# Install with uvuv 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 instanceOPEN_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:

# .envOPEN_NOTEBOOK_URL=http://localhost:5055

If you've configured authentication in Open Notebook:

# .envOPEN_NOTEBOOK_URL=http://localhost:5055OPEN_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 toolssearch_capabilities(query="", detail="summary", limit=50)
# Search for specific functionalitysearch_capabilities(query="notebook", detail="summary", limit=10)
# Get full details for a specific toolsearch_capabilities(query="create_notebook", detail="full", limit=1)

Example Workflows

Creating and Managing Notebooks

# Create a new notebookresult = create_notebook(    name="AI Research",    description="Research on AI applications")notebook_id = result["notebook"]["id"]
# List all notebooksnotebooks = list_notebooks(archived=False, limit=20)
# Update a notebookupdate_notebook(    notebook_id=notebook_id,    name="AI Research (Updated)")
# Get a specific notebooknotebook = get_notebook(notebook_id=notebook_id)

Adding Sources

# Add a web sourcesource = create_source(    notebook_id=notebook_id,    type="link",    url="https://example.com/ai-article",    title="AI Research Article",    embed=True  # Generate embeddings)
# List sources in a notebooksources = list_sources(notebook_id=notebook_id, limit=20)

Creating Notes

# Create a notenote = create_note(    notebook_id=notebook_id,    title="Key Findings",    content="Important insights about AI applications...",    topics=["AI", "Research"])
# Update a noteupdate_note(    note_id=note["note"]["id"],    content="Updated insights...")

Searching and Asking Questions

# Search contentresults = search(    query="artificial intelligence",    type="vector",    notebook_id=notebook_id,    limit=10)
# List available models firstmodels = list_models(limit=50)model_id = models["models"][0]["id"]
# Ask a questionanswer = ask_simple(    question="What are the main AI applications mentioned?",    strategy_model=model_id,    answer_model=model_id,    final_answer_model=model_id,    notebook_id=notebook_id)

Chat Sessions

# Create a chat sessionsession = create_chat_session(    notebook_id=notebook_id,    title="Research Discussion")session_id = session["session"]["id"]
# Build contextcontext = get_chat_context(notebook_id=notebook_id)
# Send a messageresponse = execute_chat(    session_id=session_id,    message="What are the key insights from my research?",    context=context["context"])
# Get session historyhistory = get_chat_session(session_id=session_id)

Available Tools

The server provides 39 tools across multiple categories:

Meta Tools

• search_capabilities - Progressive tool discovery

Notebooks (5 tools)

• list_notebooks, get_notebook, create_notebook, update_notebook, delete_notebook

Sources (5 tools)

• list_sources, get_source, create_source, update_source, delete_source

Notes (5 tools)

• list_notes, get_note, create_note, update_note, delete_note

Search (3 tools)

• search, ask_question, ask_simple

Models (5 tools)

• list_models, get_model, create_model, delete_model, get_default_models

Chat (7 tools)

• list_chat_sessions, create_chat_session, get_chat_session, update_chat_session, delete_chat_session, execute_chat, get_chat_context

Settings (2 tools)

• get_settings, update_settings

Architecture

This server follows MCP best practices:

• Progressive Disclosure: Use search_capabilities to minimize context usage
• Context Efficiency: Small outputs by default, with limit parameters
• Dual Transport: Supports both STDIO (local) and Streamable HTTP (remote)
• Error Handling: Structured error messages with actionable hints
• Timeouts: 30-second default timeout for all API requests
• Authentication: Optional Bearer token authentication

Development

Project Structure

open-notebook-mcp/├── src/│   └── open_notebook_mcp/│       ├── __init__.py│       └── server.py          # Main MCP server implementation├── tests/                      # (to be added)├── pyproject.toml├── README.md└── .env.example

Testing

Test the server using the MCP Inspector:

mcp dev src/open_notebook_mcp/server.py

or

npx @modelcontextprotocol/inspector uv --directory ./src/open_notebook_mcp "run" "server.py"

This opens an interactive inspector where you can:

1. Browse available tools
2. Test tool calls
3. Inspect responses
4. Debug errors

Adding New Tools

To add new tools:

1. Add a Capability entry to the CAPABILITIES tuple
2. Implement the tool function with @mcp.tool() decorator
3. Follow naming conventions: verb_noun (e.g., list_notebooks)
4. Include proper docstrings and type hints
5. Return structured responses with request_id

Requirements

• Python 3.12+
• Open Notebook instance (local or remote)
• Dependencies: mcp[cli]>=1.23.2, httpx>=0.28.1

Contributing

Contributions are welcome! Please ensure:

• Follow the existing code structure and patterns
• Add tools to the CAPABILITIES index
• Include proper type hints and docstrings
• Test with MCP Inspector before submitting

License

See LICENSE file for details.

Links

• Open Notebook
• Open Notebook API Reference
• Model Context Protocol
• FastMCP Documentation

Support

For issues related to:

• This MCP server: Open an issue in this repository
• Open Notebook itself: Visit the Open Notebook repository
• MCP protocol: Check the MCP documentation