| name | mcp-jupyter |
| description | Reference for MCP Jupyter tools (kernel management, cell execution, Papermill). Use when executing notebooks, managing kernels, or running code interactively via MCP. |
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",
mode="sync"
)
Python notebooks - Cell-by-cell (for control)
manage_kernel(action="start", kernel_name="python3")
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")
execute_on_kernel(
kernel_id="...", mode="code",
code='System.IO.Directory.SetCurrentDirectory(@"d:\\dev\\CoursIA\\MyIA.AI.Notebooks\\Sudoku");'
)
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 |
