MCP Jupyter Reference
When to Use MCP vs Local Scripts
| Need |
Tool |
Why |
| Batch validation (Python) |
scripts/notebook_tools/notebook_tools.py validate |
Faster, no kernel setup |
| Batch execution (Python) |
scripts/notebook_tools/notebook_tools.py execute |
Papermill CLI, simpler |
| Structure analysis |
scripts/notebook_tools/notebook_helpers.py list --verbose |
Local, instant |
| Find enrichment gaps |
NotebookHelper.find_cells_needing_enrichment() |
Python API |
| Cell-by-cell .NET execution |
MCP execute_on_kernel |
Only option (Papermill blocked) |
| Interactive debugging |
MCP manage_kernel + execute_on_kernel |
Live kernel state |
| Notebook read/write via API |
MCP read_cells, add_cell |
Remote/programmatic |
Rule: Prefer local scripts for Python notebooks. Use MCP for .NET kernels and interactive sessions. See notebook-helpers skill for full script reference.
Available MCP Tools
| Tool |
Description |
list_kernels() |
List available kernel specs |
manage_kernel(action, kernel_name/id) |
start/stop/restart/interrupt kernel |
execute_on_kernel(kernel_id, mode, ...) |
Execute code, cell, or full notebook |
execute_notebook(input_path, ...) |
Papermill execution (sync/async) |
read_notebook(path) |
Read notebook content |
read_cells(path, mode) |
Read cells (list/summary) |
get_notebook_info(path) |
Notebook metadata |
manage_async_job(action, job_id) |
Manage async Papermill jobs |
Supported Kernels
| Kernel |
Name |
Notes |
| Python 3 |
python3 |
Via ipykernel in conda mcp-jupyter-py310 |
| .NET C# |
.net-csharp |
Via dotnet-interactive |
| .NET F# |
.net-fsharp |
Via dotnet-interactive |
| Lean 4 |
lean4 |
Via WSL wrapper |
Execution Patterns
Python notebooks - Papermill (preferred for batch)
execute_notebook(
input_path="MyIA.AI.Notebooks/path/notebook.ipynb",
output_path="MyIA.AI.Notebooks/path/notebook.ipynb", # Same file = overwrite with outputs
mode="sync"
)
Python notebooks - Cell-by-cell (for control)
manage_kernel(action="start", kernel_name="python3")
# Execute cells
execute_on_kernel(kernel_id="...", mode="notebook_cell", path="notebook.ipynb", cell_index=0)
# ...
manage_kernel(action="stop", kernel_id="...")
.NET notebooks - Cell-by-cell ONLY
IMPORTANT: Papermill does NOT work with .NET notebooks. Always use cell-by-cell.
manage_kernel(action="start", kernel_name=".net-csharp")
# CRITICAL: Set working directory first
execute_on_kernel(
kernel_id="...", mode="code",
code='System.IO.Directory.SetCurrentDirectory(@"d:\\dev\\CoursIA\\MyIA.AI.Notebooks\\Sudoku");'
)
# Execute cells sequentially
for idx in range(cell_count):
execute_on_kernel(kernel_id="...", mode="notebook_cell", path="notebook.ipynb", cell_index=idx)
manage_kernel(action="stop", kernel_id="...")
Known Issues
| Problem |
Workaround |
Papermill + #!import |
Use cell-by-cell execution |
| Papermill + .NET kernels |
Kernel hangs at startup; use cell-by-cell |
| .NET cold start timeout |
Normal (30-60s); retry once |
| Async progress values incorrect |
Known bug; ignore progress numbers |
| Kernel unresponsive after failed Papermill |
Stop and restart kernel |
| Relative paths fail |
Set working directory explicitly |
| Widgets/interactive elements |
Use BATCH_MODE=true parameter |
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
1---2name: mcp-jupyter3description: Reference for MCP Jupyter tools (kernel management, cell execution, Papermill). Use when executing notebooks, managing kernels, or running code interactively via MCP. Use when this capability is needed.4---56# MCP Jupyter Reference78## When to Use MCP vs Local Scripts910| Need | Tool | Why |11|------|------|-----|12| Batch validation (Python) | `scripts/notebook_tools/notebook_tools.py validate` | Faster, no kernel setup |13| Batch execution (Python) | `scripts/notebook_tools/notebook_tools.py execute` | Papermill CLI, simpler |14| Structure analysis | `scripts/notebook_tools/notebook_helpers.py list --verbose` | Local, instant |15| Find enrichment gaps | `NotebookHelper.find_cells_needing_enrichment()` | Python API |16| Cell-by-cell .NET execution | **MCP** `execute_on_kernel` | Only option (Papermill blocked) |17| Interactive debugging | **MCP** `manage_kernel` + `execute_on_kernel` | Live kernel state |18| Notebook read/write via API | **MCP** `read_cells`, `add_cell` | Remote/programmatic |1920**Rule**: Prefer local scripts for Python notebooks. Use MCP for .NET kernels and interactive sessions. See `notebook-helpers` skill for full script reference.2122## Available MCP Tools2324| Tool | Description |25|------|-------------|26| `list_kernels()` | List available kernel specs |27| `manage_kernel(action, kernel_name/id)` | start/stop/restart/interrupt kernel |28| `execute_on_kernel(kernel_id, mode, ...)` | Execute code, cell, or full notebook |29| `execute_notebook(input_path, ...)` | Papermill execution (sync/async) |30| `read_notebook(path)` | Read notebook content |31| `read_cells(path, mode)` | Read cells (list/summary) |32| `get_notebook_info(path)` | Notebook metadata |33| `manage_async_job(action, job_id)` | Manage async Papermill jobs |3435## Supported Kernels3637| Kernel | Name | Notes |38|--------|------|-------|39| Python 3 | `python3` | Via ipykernel in conda `mcp-jupyter-py310` |40| .NET C# | `.net-csharp` | Via dotnet-interactive |41| .NET F# | `.net-fsharp` | Via dotnet-interactive |42| Lean 4 | `lean4` | Via WSL wrapper |4344## Execution Patterns4546### Python notebooks - Papermill (preferred for batch)4748```python49execute_notebook(50 input_path="MyIA.AI.Notebooks/path/notebook.ipynb",51 output_path="MyIA.AI.Notebooks/path/notebook.ipynb", # Same file = overwrite with outputs52 mode="sync"53)54```5556### Python notebooks - Cell-by-cell (for control)5758```python59manage_kernel(action="start", kernel_name="python3")60# Execute cells61execute_on_kernel(kernel_id="...", mode="notebook_cell", path="notebook.ipynb", cell_index=0)62# ...63manage_kernel(action="stop", kernel_id="...")64```6566### .NET notebooks - Cell-by-cell ONLY6768**IMPORTANT**: Papermill does NOT work with .NET notebooks. Always use cell-by-cell.6970```python71manage_kernel(action="start", kernel_name=".net-csharp")7273# CRITICAL: Set working directory first74execute_on_kernel(75 kernel_id="...", mode="code",76 code='System.IO.Directory.SetCurrentDirectory(@"d:\\dev\\CoursIA\\MyIA.AI.Notebooks\\Sudoku");'77)7879# Execute cells sequentially80for idx in range(cell_count):81 execute_on_kernel(kernel_id="...", mode="notebook_cell", path="notebook.ipynb", cell_index=idx)8283manage_kernel(action="stop", kernel_id="...")84```8586## Known Issues8788| Problem | Workaround |89|---------|------------|90| Papermill + `#!import` | Use cell-by-cell execution |91| Papermill + .NET kernels | Kernel hangs at startup; use cell-by-cell |92| .NET cold start timeout | Normal (30-60s); retry once |93| Async progress values incorrect | Known bug; ignore progress numbers |94| Kernel unresponsive after failed Papermill | Stop and restart kernel |95| Relative paths fail | Set working directory explicitly |96| Widgets/interactive elements | Use BATCH_MODE=true parameter |9798---99> Converted and distributed by [TomeVault](https://tomevault.io/claim/jsboige) — claim your Tome and manage your conversions.100<!-- tomevault:4.0:skill_md:2026-04-11 -->
tomevault-io