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