Open Notebook MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Open Notebook MCP Server create a new notebook for research notes"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Using uv (recommended)
# Clone the repository
git clone https://github.com/PiotrAleksander/open-notebook-mcp.git
cd open-notebook-mcp
# Install with uv
uv syncUsing 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 deploymentExample Configuration
For local development with default Open Notebook settings:
# .env
OPEN_NOTEBOOK_URL=http://localhost:5055If you've configured authentication in Open Notebook:
# .env
OPEN_NOTEBOOK_URL=http://localhost:5055
OPEN_NOTEBOOK_PASSWORD=my_secure_passwordUsage
Running the Server
Development Mode (STDIO)
For local use with AI assistants:
uv run open-notebook-mcpOr using the MCP CLI:
mcp dev src/open_notebook_mcp/server.pyProduction Mode (Streamable HTTP)
For remote deployment:
MCP_TRANSPORT=streamable-http HOST=0.0.0.0 PORT=8000 uv run open-notebook-mcpUsing 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_capabilitiesto minimize context usageContext 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.exampleTesting
Test the server using the MCP Inspector:
mcp dev src/open_notebook_mcp/server.pyor
npx @modelcontextprotocol/inspector uv --directory ./src/open_notebook_mcp "run" "server.py"This opens an interactive inspector where you can:
Browse available tools
Test tool calls
Inspect responses
Debug errors
Adding New Tools
To add new tools:
Add a
Capabilityentry to theCAPABILITIEStupleImplement the tool function with
@mcp.tool()decoratorFollow naming conventions:
verb_noun(e.g.,list_notebooks)Include proper docstrings and type hints
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
CAPABILITIESindexInclude proper type hints and docstrings
Test with MCP Inspector before submitting
License
See LICENSE file for details.
Links
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
Available Tools
33 toolsask_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
searchB
Search content using vector or text search.
Args:
query: Search query
type: Search type ('vector' or 'text')
notebook_id: Optional notebook ID to limit search
limit: Maximum number of results (1-50)
Returns:
Search results
Inputs: query (required), type, notebook_id, limit. 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
Scored across 33 tools
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.
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.
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.
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
Related MCP Connectors
Create, search, and update notes in an xNotepad AI notebook, with semantic search and AI Q&A.
Create, search and manage Knowtis collaborative notes from AI assistants.
Enables AI assistants to retrieve event data and execute event management operations in Nunify.
Secure AI access to OpenOak tasks, notes, and Kanban boards.
Related MCP Servers
- AlicenseBqualityAmaintenanceEnables 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.5518,759 PyPI6,540MIT
- AlicenseAqualityBmaintenanceMCP 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.27298 npm24MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to programmatically access and control Google NotebookLM, supporting operations like notebook management, source addition, audio generation, and more via natural language.39MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage Google NotebookLM notebooks, add sources from URLs, YouTube, Drive, or text, query and summarize content, and generate audio overviews, infographics, and slide decks through natural language.MIT