query_notebook
Query Jupyter notebook information and metadata, including source code, server status, sessions, and cell positions.
Instructions
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 indexExamples
# 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 serverInput Schema
| Name | Required | Description | Default |
|---|---|---|---|
| notebook_path | Yes | ||
| query_type | Yes | ||
| execution_count | No | ||
| position_index | No | ||
| cell_id | No | ||
| server_url | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |