Skip to main content
Glama
Open Notebook MCP Server

Open Notebook MCP Server

by Epochal-dev

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

Related MCP server: NotebookLM MCP

Installation

# 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",
    title="AI Research Article",
    embed=True  # Generate embeddings
)

# List sources in a notebook
sources = list_sources(notebook_id=notebook_id, limit=20)

Creating Notes

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

# Update a note
update_note(
    note_id=note["note"]["id"],
    content="Updated insights..."
)

Searching and Asking Questions

# Search content
results = search(
    query="artificial intelligence",
    type="vector",
    notebook_id=notebook_id,
    limit=10
)

# List available models first
models = list_models(limit=50)
model_id = models["models"][0]["id"]

# Ask a question
answer = 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 session
session = create_chat_session(
    notebook_id=notebook_id,
    title="Research Discussion"
)
session_id = session["session"]["id"]

# Build context
context = get_chat_context(notebook_id=notebook_id)

# Send a message
response = execute_chat(
    session_id=session_id,
    message="What are the key insights from my research?",
    context=context["context"]
)

# Get session history
history = 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.

Support

For issues related to:

Available Tools

33 tools
ask_questionC

Ask a question about your content with detailed control.

Args:
    question: Question to ask
    strategy_model: Model ID for strategy generation
    answer_model: Model ID for answering
    final_answer_model: Model ID for final answer synthesis
    notebook_id: Optional notebook ID to limit context

Returns:
    Answer with sources and reasoning

Inputs: question (required), strategy_model (required), answer_model (required), final_answer_model (required), +1 more. Returns: object

ask_simpleC

Ask a question about your content with simplified interface.

Args:
    question: Question to ask
    strategy_model: Model ID for strategy generation
    answer_model: Model ID for answering
    final_answer_model: Model ID for final answer synthesis
    notebook_id: Optional notebook ID to limit context

Returns:
    Simple answer

Inputs: question (required), strategy_model (required), answer_model (required), final_answer_model (required), +1 more. Returns: object

create_chat_sessionC

Create a new chat session.

Args:
    notebook_id: Notebook ID for the session
    title: Session title

Returns:
    Created session details

Inputs: notebook_id (required), title (required). Returns: object

create_modelC

Create a new AI model configuration.

Args:
    name: Model name (e.g., 'gpt-4', 'claude-3-opus')
    provider: Provider name (e.g., 'openai', 'anthropic')
    type: Model type (e.g., 'language', 'embedding')

Returns:
    Created model details

Inputs: name (required), provider (required), type (required). Returns: object

create_noteB

Create a new note.

Args:
    notebook_id: Notebook ID to add note to
    title: Note title
    content: Note content
    topics: Optional list of topics

Returns:
    Created note details

Inputs: notebook_id (required), title (required), content (required), topics. Returns: object

create_notebookC

Create a new notebook.

Args:
    name: Notebook name
    description: Optional notebook description

Returns:
    Created notebook details

Inputs: name (required), description. Returns: object

create_sourceC

Create a new source (link, upload, or text).

Args:
    notebook_id: Notebook ID to add source to
    type: Source type ('link', 'upload', or 'text')
    url: URL for link type sources
    title: Optional title
    embed: Whether to generate embeddings (default: True)

Returns:
    Created source details

Inputs: notebook_id (required), type (required), url, title, +1 more. Returns: object

delete_chat_sessionC

Delete a chat session.

Args:
    session_id: Session ID

Returns:
    Success message

Inputs: session_id (required). Returns: object

delete_modelC

Delete a model configuration.

Args:
    model_id: Model ID

Returns:
    Success message

Inputs: model_id (required). Returns: object

delete_noteC

Delete a note.

Args:
    note_id: Note ID

Returns:
    Success message

Inputs: note_id (required). Returns: object

delete_notebookC

Delete a notebook.

Args:
    notebook_id: Notebook ID

Returns:
    Success message

Inputs: notebook_id (required). Returns: object

delete_sourceB

Delete a source.

Args:
    source_id: Source ID

Returns:
    Success message

Inputs: source_id (required). Returns: object

execute_chatC

Send a message in a chat session.

Args:
    session_id: Session ID
    message: Message to send
    context: Optional context data for the conversation

Returns:
    Chat response with AI message

Inputs: session_id (required), message (required), context. Returns: object

get_chat_contextC

Build context for a chat conversation.

Args:
    notebook_id: Notebook ID
    context_config: Optional context configuration

Returns:
    Built context data

Inputs: notebook_id (required), context_config. Returns: object

get_chat_sessionA

Get a specific chat session by ID.

Args:
    session_id: Session ID (e.g., 'session:abc123')

Returns:
    Session details with message history

Inputs: session_id (required). Returns: object

get_default_modelsA

Get default model configurations.

Returns:
    Default models configuration

Inputs: no named parameters. Returns: object

get_modelB

Get a specific model by ID.

Args:
    model_id: Model ID (e.g., 'model:abc123')

Returns:
    Model details

Inputs: model_id (required). Returns: object

get_noteB

Get a specific note by ID.

Args:
    note_id: Note ID (e.g., 'note:abc123')

Returns:
    Note details

Inputs: note_id (required). Returns: object

get_notebookB

Get a specific notebook by ID.

Args:
    notebook_id: Notebook ID (e.g., 'notebook:abc123')

Returns:
    Notebook details

Inputs: notebook_id (required). Returns: object

get_settingsB

Get application settings.

Returns:
    Application settings

Inputs: no named parameters. Returns: object

get_sourceA

Get a specific source by ID.

Args:
    source_id: Source ID (e.g., 'source:abc123')

Returns:
    Source details

Inputs: source_id (required). Returns: object

list_chat_sessionsB

Get all chat sessions with optional filtering.

Args:
    notebook_id: Optional notebook ID to filter by
    limit: Maximum number of results (1-100)

Returns:
    Dictionary with sessions list and metadata

Inputs: notebook_id, limit. Returns: object

list_modelsB

Get all configured AI models.

Args:
    limit: Maximum number of results (1-100)

Returns:
    Dictionary with models list and metadata

Inputs: limit. Returns: object

list_notebooksA

Get all notebooks with optional filtering and ordering.

Args:
    archived: Filter by archived status (None = all, True = archived only, False = active only)
    order_by: Order by field and direction (e.g., 'created desc', 'name asc')
    limit: Maximum number of results (1-100)

Returns:
    Dictionary with notebooks list and metadata

Inputs: archived, order_by, limit. Returns: object

list_notesA

Get all notes with optional filtering.

Args:
    notebook_id: Optional notebook ID to filter by
    limit: Maximum number of results (1-100)
    offset: Pagination offset

Returns:
    Dictionary with notes list and metadata

Inputs: notebook_id, limit, offset. Returns: object

list_sourcesA

Get all sources with optional filtering.

Args:
    notebook_id: Optional notebook ID to filter by
    limit: Maximum number of results (1-100)
    offset: Pagination offset

Returns:
    Dictionary with sources list and metadata

Inputs: notebook_id, limit, offset. Returns: object

search_capabilitiesA

Search tools exposed by this server with progressive detail levels.

Args:
    query: Search query to filter tools
    detail: Level of detail - 'name' (minimal), 'summary' (default), or 'full' (complete)
    limit: Maximum number of results (1-50)

Returns:
    Dictionary with request_id, query, detail, count, matches, and hint fields

Inputs: query, detail, limit. Returns: object

update_chat_sessionC

Update a chat session.

Args:
    session_id: Session ID
    title: Optional new title

Returns:
    Updated session details

Inputs: session_id (required), title. Returns: object

update_noteC

Update a note.

Args:
    note_id: Note ID
    title: Optional new title
    content: Optional new content
    topics: Optional list of topics

Returns:
    Updated note details

Inputs: note_id (required), title, content, topics. Returns: object

update_notebookA

Update a notebook.

Args:
    notebook_id: Notebook ID
    name: Optional new name
    description: Optional new description
    archived: Optional archived status

Returns:
    Updated notebook details

Inputs: notebook_id (required), name, description, archived. Returns: object

update_settingsC

Update application settings.

Args:
    settings: Settings dictionary to update

Returns:
    Updated settings

Inputs: settings (required). Returns: object

update_sourceC

Update a source.

Args:
    source_id: Source ID
    title: Optional new title
    topics: Optional list of topics

Returns:
    Updated source details

Inputs: source_id (required), title, topics. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 33 tools

    Disambiguation4/5

    Most tools have clear distinct purposes, but 'ask_question' and 'ask_simple' are very similar in functionality and arguments, potentially causing confusion for an agent. Other tools like CRUD operations are well-separated.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with lowercase and underscores (e.g., create_notebook, delete_source). No mixing of conventions or irregular names.

    Tool Count4/5

    With 33 tools, the server is on the higher side but still reasonable given the multiple resources (notebooks, notes, sources, chat sessions, models, settings) and additional utility tools. It's slightly over the typical well-scoped range but not excessive.

    Completeness4/5

    The tool surface covers CRUD operations for all major resources and includes question-asking and search features. Minor gaps like import/export or bulk operations are missing, but core workflows are well-supported.

    Maintenance

    ActivityInactive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      A
      maintenance
      Enables AI assistants to programmatically interact with Google NotebookLM, allowing them to create and manage notebooks, add sources, query content, generate audio/video, and perform research tasks through natural language commands.
      55
      18,759 PyPI
      6,540
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      MCP server for Google NotebookLM. 27 tools to manage notebooks and sources (web pages, YouTube, text, Google Drive), ask questions answered only from your sources, run web research, and generate Audio and Video Overviews, slide decks, reports, infographics, flashcards and quizzes. Every tool has MCP annotations and a typed output schema. Runs locally with your own Google session.
      27
      298 npm
      24
      MIT