Skip to main content

Tools

The server currently offers 14 tools organized into 3 categories:

Server Management (2 tools)​

1. list_files​

  • List all files and directories recursively in the Jupyter server's file system.
  • Used to explore the file system structure of the Jupyter server or to find specific files or directories.
  • Input:
    • path(string, optional): The starting path to list from (empty string means root directory, default: "")
    • max_depth(int, optional): Maximum depth to recurse into subdirectories (default: 1, max: 3)
    • start_index(int, optional): Starting index for pagination (0-based, default: 0)
    • limit(int, optional): Maximum number of items to return (0 means no limit, default: 25)
    • pattern(string, optional): Glob pattern to filter file paths (default: "")
  • Returns: Tab-separated table with columns: Path, Type, Size, Last_Modified. Includes pagination info header showing current range and total count.
    • Path: Full path to the file or directory
    • Type: File type ("file", "directory", "notebook", or "error" if inaccessible)
    • Size: File size formatted as B, KB, or MB (empty for directories)
    • Last_Modified: Last modification timestamp in YYYY-MM-DD HH:MM:SS format

2. list_kernels​

  • List all available kernels in the Jupyter server.
  • This tool shows all running and available kernel sessions on the Jupyter server, including their IDs, names, states, connection information, and kernel specifications. Useful for monitoring kernel resources and identifying specific kernels for connection.
  • Input: None
  • Returns: Tab-separated table with columns: ID, Name, Display_Name, Language, State, Connections, Last_Activity, Environment
    • ID: Unique kernel identifier
    • Name: Kernel name/type (e.g., "python3", "ir", etc.)
    • Display_Name: Human-readable kernel name from kernel spec
    • Language: Programming language supported by the kernel
    • State: Current execution state ("idle", "busy", "unknown")
    • Connections: Number of active connections to this kernel
    • Last_Activity: Timestamp of last kernel activity in YYYY-MM-DD HH:MM:SS format
    • Environment: Environment variables defined in the kernel spec (truncated if long)

Multi-Notebook (5 tools)​

3. use_notebook​

  • Use a notebook and activate it for following cell operations.
  • Input:
    • notebook_name(string): Unique identifier for the notebook
    • notebook_path(string): Path to the notebook file, relative to the Jupyter server root (e.g. "notebook.ipynb")
    • mode(string): Notebook operation mode: "connect" to connect to existing and activate it, "create" to create new and activate it (default: "connect")
    • kernel_id(string, optional): Specific kernel ID to use (will create new if skipped)
  • Returns: Success message with notebook information including activation status, kernel details, and notebook overview

4. list_notebooks​

  • List all notebooks that have been used via use_notebook tool.
  • Input: None
  • Returns: TSV formatted table with notebook information
    • Name: Unique identifier for the notebook
    • Path: Path to the notebook file
    • Kernel_ID: Kernel ID associated with the notebook
    • Kernel_Status: Current status of the kernel
    • Activate: "✓" if this is the currently active notebook, empty otherwise

5. restart_notebook​

  • Restart the kernel for a specific notebook.
  • Input:
    • notebook_name(string): Notebook identifier to restart
  • Returns: Success message confirming the kernel has been restarted and memory state cleared

6. unuse_notebook​

  • Unuse from a specific notebook and release its resources.
  • Input:
    • notebook_name(string): Notebook identifier to disconnect
  • Returns: Success message confirming the notebook has been disconnected and resources released

7. read_notebook​

  • Read a notebook and return index, source content, type, execution count of each cell.
  • Using brief format to get a quick overview of the notebook structure and it's useful for locating specific cells for operations like delete or insert.
  • Using detailed format to get detailed information of the notebook and it's useful for debugging and analysis.
  • It is recommended to use brief format with larger limit to get a overview of the notebook structure, then use detailed format with exact index and limit to get the detailed information of some specific cells.
  • Input:
    • notebook_name(string): Notebook identifier to read
    • response_format(string): Response format: "brief" will return first line and lines number, "detailed" will return full cell source (default: "brief")
    • start_index(int, optional): Starting index for pagination (0-based, default: 0)
    • limit(int, optional): Maximum number of items to return (0 means no limit, default: 20)
  • Returns: Notebook content in the requested format with cell details, metadata, and pagination information

Cell Tools (7 tools)​

8. insert_cell​

  • Insert a cell to specified position from the currently activated notebook.
  • Input:
    • cell_index(int): Target index for insertion (0-based), use -1 to append at end
    • cell_type(string): Type of cell to insert ("code" or "markdown")
    • cell_source(string): Source content for the cell
  • Returns: Success message with insertion confirmation and the structure of surrounding cells (up to 5 cells above and below)

9. overwrite_cell_source​

  • Overwrite the source of a specific cell from the currently activated notebook.
  • It will return a diff style comparison (e.g. + for new lines, - for deleted lines) of the cell's content
  • Input:
    • cell_index(int): Index of the cell to overwrite (0-based)
    • cell_source(string): New complete cell source
  • Returns: Success message with diff style comparison showing changes made (e.g. + for new lines, - for deleted lines)

10. execute_cell​

  • Execute a cell from the currently activated notebook with timeout and return it's outputs
  • Input:
    • cell_index(int): Index of the cell to execute (0-based)
    • timeout(int, optional): Maximum seconds to wait for execution (default: 90)
    • stream(bool, optional): Enable streaming progress updates for long-running cells (default: false)
    • progress_interval(int, optional): Seconds between progress updates when stream=true (default: 5)
  • Returns: list[Union[str, ImageContent]] - List of outputs from the executed cell including text, HTML, and images. Supports streaming mode with progress updates for long-running cells.

11. insert_execute_code_cell​

  • Insert a cell at specified index from the currently activated notebook and then execute it with timeout and return it's outputs.
  • It is a shortcut tool for insert_cell and execute_cell tools, recommended to use if you want to insert a cell and execute it at the same time
  • Input:
    • cell_index(int): Index of the cell to insert and execute (0-based)
    • cell_source(string): Code source for the cell
    • timeout(int, optional): Maximum seconds to wait for execution (default: 90)
  • Returns: list[Union[str, ImageContent]] - List of outputs from the executed cell including text, HTML, and images. Returns both insertion confirmation and execution results.

12. read_cell​

  • Read a specific cell from the currently activated notebook and return it's metadata (index, type, execution count), source and outputs (for code cells)
  • Input:
    • cell_index(int): Index of the cell to read (0-based)
    • include_outputs(bool, optional): Include outputs in the response (only for code cells, default: true)
  • Returns: list[Union[str, ImageContent]] - List containing cell metadata (index, type, execution count), source code, and outputs (for code cells with include_outputs=true)

13. delete_cell​

  • Delete a specific cell or multiple cells from the currently activated notebook and return the cell source of deleted cells (if include_source=True).
  • When deleting many cells, MUST delete them in descending order of their index to avoid index shifting.
  • Input:
    • cell_indices(list[int]): List of indices of the cells to delete (0-based)
    • include_source(bool, optional): Whether to include the source of deleted cells (default: true)
  • Returns: Success message with deletion confirmation and the source code of the deleted cells (if include_source=True)

14. execute_code​

  • Execute code directly in the kernel (not saved to notebook) on the current activated notebook.
  • Recommended to use in following cases:
    1. Execute Jupyter magic commands (e.g., %timeit, %pip install xxx)
    2. Performance profiling and debugging
    3. View intermediate variable values (e.g., print(xxx), df.head())
    4. Temporary calculations and quick tests (e.g., np.mean(df['xxx']))
    5. Execute Shell commands in Jupyter server (e.g., !git xxx)
  • Under no circumstances should you use this tool to:
    1. Import new modules or perform variable assignments that affect subsequent Notebook execution
    2. Execute dangerous code that may harm the Jupyter server or the user's data without permission
  • Input:
    • code(string): Code to execute (supports magic commands with %, shell commands with !)
    • timeout(int, optional): Execution timeout in seconds (default: 30, max: 60)
  • Returns: list[Union[str, ImageContent]] - List of outputs from the executed code including text, HTML, images, and shell command results. Supports magic commands and shell commands with ! prefix.