Query notebook information and metadata on the user-provided server.

This consolidates all read-only operations into a single tool following MCP best practices.

IMPORTANT: Server URL Configuration

This tool requires a server URL to connect to your Jupyter server. You have two options:

Option 1 - Call setup_notebook first (RECOMMENDED): setup_notebook("my_notebook", server_url="http://localhost:9999") query_notebook("my_notebook", "view_source") # Uses stored URL automatically

Option 2 - Pass server_url explicitly every time: query_notebook("my_notebook", "view_source", server_url="http://localhost:9999")

If neither is done, it defaults to http://localhost:8888 which may not be correct.

Args: notebook_path: Path to the notebook file (.ipynb extension will be added if missing), relative to the Jupyter server root. query_type: Type of query to perform. Options: - 'view_source': View source code of notebook (single cell or all cells) - 'check_server': Check if Jupyter server is running and accessible - 'list_sessions': List all notebook sessions on the server - 'get_position_index': Get the index of a code cell execution_count: (For view_source/get_position_index) The execution count to look for. IMPORTANT: This is the number shown in square brackets like [3] in Jupyter UI. Only available for executed code cells. Must be an integer (e.g., 3). COMMON MISTAKE: Don't confuse with position_index! - execution_count=3 finds the cell that was executed 3rd (shows [3] in Jupyter) - position_index=3 finds the 4th cell in the notebook (0-indexed position) position_index: (For view_source) The position index to look for. This is the cell's physical position in the notebook (0-indexed). Examples: first cell = 0, second cell = 1, third cell = 2, etc. Works for all cell types (code, markdown, raw). Must be an integer. cell_id: (For get_position_index) Cell ID like "205658d6-093c-4722-854c-90b149f254ad". This is a unique identifier for each cell, visible in notebook metadata. server_url: Server URL to connect to. If not provided, uses the URL stored by setup_notebook, or falls back to http://localhost:8888

Returns

Union[dict, list, str, int]:
    - view_source: dict (single cell) or list[dict] (all cells) with cell contents/metadata
    - check_server: str status message
    - list_sessions: list of notebook sessions
    - get_position_index: int positional index

Examples

# View all cells in notebook
query_notebook("my_notebook.ipynb", "view_source")

# View cell by execution count (the [3] shown in Jupyter UI)
query_notebook("my_notebook.ipynb", "view_source", execution_count=3)

# View cell by position (first cell=0, second=1, etc)
query_notebook("my_notebook.ipynb", "view_source", position_index=0)

# Get position index of cell with execution count [5]
query_notebook("my_notebook.ipynb", "get_position_index", execution_count=5)

# Get position index by cell ID
query_notebook("my_notebook.ipynb", "get_position_index", cell_id="205658d6-093c-4722-854c-90b149f254ad")

Raises

ValueError: If invalid query_type or missing required parameters
McpError: If there's an error connecting to the Jupyter server

Modify notebook cells (add, edit, delete) on the user-provided server.

This consolidates all cell modification operations into a single tool following MCP best practices. Default to execute=True unless the user requests otherwise or you have good reason not to execute immediately.

IMPORTANT: Server URL Configuration

This tool requires that you first call setup_notebook with the correct server URL:

Required setup: setup_notebook("my_notebook", server_url="http://localhost:9999")

Then you can use this tool: modify_notebook_cells("my_notebook", "add_code", "print('Hello')")

Without setup_notebook, this will try to connect to http://localhost:8888 by default.

Args: notebook_path: Path to the notebook file (.ipynb extension will be added if missing), relative to the Jupyter server root. operation: Type of cell operation. Options: - 'add_code': Add (and optionally execute) a code cell at end or specific position - 'edit_code': Edit a code cell at specific position - 'add_markdown': Add a markdown cell at end or specific position - 'edit_markdown': Edit an existing markdown cell at specific position - 'delete': Delete a cell at specific position cell_content: Content for the cell (required for add_code, edit_code, add_markdown, edit_markdown) position_index: Position index (0-indexed cell location) for operations. Must be an integer. - Optional for add_code/add_markdown: if provided, inserts at that position; if not, adds at end - Required for edit_code/edit_markdown/delete: specifies which cell to modify Examples: position_index=0 (first cell), position_index=2 (third cell) execute: Whether to execute code cells after adding/editing (default: True)

Returns

dict: Operation results containing:
    - For add_code/edit_code with execute=True: execution_count, outputs, status
    - For add_code/edit_code with execute=False: empty dict
    - For add_markdown/edit_markdown: message and error fields
    - For delete: message and error fields

Raises

ValueError: If invalid operation or missing required parameters
McpError: If there's an error connecting to the Jupyter server
IndexError: If position_index is out of range

Execute code in a Jupyter notebook on the user-provided server.

This consolidates all code execution operations into a single tool following MCP best practices.

IMPORTANT: Server URL Configuration

This tool requires that you first call setup_notebook with the correct server URL:

Required setup: setup_notebook("my_notebook", server_url="http://localhost:9999")

Then you can use this tool: execute_notebook_code("my_notebook", "execute_cell", position_index=0)

Without setup_notebook, this will try to connect to http://localhost:8888 by default.

Args: notebook_path: Path to the notebook file (.ipynb extension will be added if missing), relative to the Jupyter server root. execution_type: Type of execution operation. Options: - 'execute_cell': Execute an existing code cell - 'install_packages': Install packages using uv pip in the notebook environment position_index: (For execute_cell) Positional index of cell to execute package_names: (For install_packages) Space-separated list of package names to install

Returns

Union[dict, str]:
    - execute_cell: dict with execution_count, outputs, status
    - install_packages: str with installation result message

Raises

ValueError: If invalid execution_type or missing required parameters
McpError: If there's an error connecting to the Jupyter server
IndexError: If position_index is out of range
RuntimeError: If kernel execution fails

Prepare notebook for use and connect to the kernel on the user-provided server. Will create a new empty Jupyter notebook if needed on the server.

CALL THIS FIRST - This tool must be called before using other notebook tools to establish the server URL connection. All subsequent notebook operations will use the server URL stored by this tool.

This tool creates an empty notebook. To add content, use the modify_notebook_cells tool after creation:

Example usage: # Step 1: REQUIRED - Setup notebook with correct server URL setup_notebook("demo", server_url="http://localhost:9999")

# Step 2: Add cells (these now use the stored server URL automatically)
modify_notebook_cells("demo", "add_markdown", "# Title\\n\\nDescription")
modify_notebook_cells("demo", "add_code", "print('Hello World')")

This tool assumes a Jupyter server is already running and accessible at the specified server_url. It connects to this existing server to manage the notebook.

Note that notebook_path must be relative to the Jupyter server root, not an absolute filesystem path.

Args: notebook_path: Path to the notebook, relative to the Jupyter server root. server_url: Jupyter server URL (HIGHLY RECOMMENDED to specify explicitly). This URL will be stored and used for subsequent interactions with this notebook. If not provided, defaults to http://localhost:8888 which may not be correct for your setup. Common values: http://localhost:8888, http://localhost:9999, etc.

Returns

dict: Information about the notebook and status message.