I share an in-depth data science and AI project practice every month. Visit and subscribe to https://www.dataleadsfuture.com

jupyter-kernel-mcp

An MCP (Model Context Protocol) server that connects directly to a Jupyter kernel via ZMQ — no JupyterLab or Notebook server required.

Enable your AI assistant to read, create, edit, execute, and manage Jupyter Notebooks as MCP tools.

Architecture

┌──────────────┐     stdio      ┌──────────────────┐      ZMQ      ┌────────────────┐
│  AI Agent    │ ◄────────────► │ jupyter-kernel-  │ ◄──────────► │  Jupyter IPykernel  │
│  (OpenCode)  │   MCP tools    │ mcp server       │              │  (python3)     │
└──────────────┘                └──────────────────┘              └────────────────┘
                                      │
                                ┌─────┴──────┐
                                │  .ipynb     │
                                │  (on disk)  │
                                └────────────┘

The server communicates with the kernel over ZMQ channels (iopub, shell, stdin, control) and persists notebook files to disk after every modification.

Related MCP server: cursor-notebook-mcp

Prerequisites

• Python ≥ 3.10

• ipykernel installed (so the kernel can start). If not sure:

  python -m ipykernel install --user

• uv (recommended) or pip

Installation

Option A: Install from GitHub (recommended for end users)

uv tool install git+https://github.com/qtalen/jupyter-kernel-mcp.git

This makes the jupyter-kernel-mcp command available globally (managed by uv).

Option B: Install from local source (for development)

git clone https://github.com/qtalen/jupyter-kernel-mcp.git
cd jupyter-kernel-mcp
uv tool install --path . jupyter-kernel-mcp

Option C: Install via pip

pip install git+https://github.com/qtalen/jupyter-kernel-mcp.git

Register with OpenCode

Add the following mcp entry to your project's opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jupyter": {
      "type": "local",
      "command": ["jupyter-kernel-mcp", "--cell-timeout", "7200"],
      "enabled": true,
      "timeout": 7200000
    }
  }
}

Then restart OpenCode. The 8 MCP tools will appear automatically.

Available Tools

All tools are registered as @mcp.tool() and are callable by your AI agent once the MCP server is connected.

1. connect_to_jupyter

2. use_notebook

3. read_notebook

4. read_cell

5. insert_cell

6. edit_cell_source

7. delete_cell

8. execute_cell

9. execute_code

Typical Workflow

A typical AI-driven notebook session follows these steps:

connect_to_jupyter(kernel_name="python3")
  → "Kernel ready — python3"

use_notebook(path="notebooks/my_analysis.ipynb")
  → "Using notebook: C:/.../my_analysis.ipynb (0 cells)"

insert_cell(source="# My Analysis\n\n## Objective\n...", index=0, cell_type="markdown")
  → "Inserted markdown cell at index 0"

insert_cell(source="import pandas as pd\ndf = pd.read_csv('data.csv')", index=1)
  → "Inserted code cell at index 1"

execute_cell(cell_index=1)
  → [...] + "[COMPLETED in 2s]"

read_cell(cell_index=1)
  → Shows source + any output

edit_cell_source(cell_index=1, old_string="data.csv", new_string="data_v2.csv")
  → "Cell 1 updated: replaced 1 occurrence of 8 → 11 chars"

execute_cell(cell_index=1)
  → [...] + "[COMPLETED in 3s]"

delete_cell(cell_index=2)
  → "Deleted cell 2 (code)"

CLI Options

jupyter-kernel-mcp [--cell-timeout SECONDS]

Troubleshooting

Kernel fails to start

• Ensure ipykernel is installed: python -m ipykernel install --user

• Verify the kernel name. Run jupyter kernelspec list to see available kernels.

• Check for proxy issues. The server automatically adds localhost,127.0.0.1 to NO_PROXY.

No tools appear in OpenCode

• Confirm jupyter-kernel-mcp is on your PATH: jupyter-kernel-mcp --help

• Check opencode.json syntax and path.

• Restart OpenCode entirely after configuration changes.

Cell execution hangs indefinitely

• The default timeout is 7200s (2h). Use execute_cell(timeout_seconds=120) for shorter tasks.

• The kernel may be stuck. Use execute_cell(progress_interval=5) to see progress updates.

• OpenCode can cancel execution via SIGINT → the server will interrupt the kernel.

Windows-specific

• The server registers SIGBREAK (Ctrl+Break) for graceful shutdown on Windows.

• Paths with spaces are supported if quoted correctly in opencode.json.

License

MIT