Skip to main content
Glama
KJH-Sun

notebook-agent-mcp

by KJH-Sun

Notebook Agent — Stateful Notebook Execution System

A local notebook execution system that lets AI agents run Jupyter notebook cells with persistent kernel state, output persistence, and structured JSON control surface.

Quick Start

Install

# GitHub에서 직접 설치
pip install git+https://github.com/KJH-Sun/jupyter-kernel-mcp.git

# 또는 로컬 클론 후 설치
git clone https://github.com/KJH-Sun/jupyter-kernel-mcp.git
cd notebook-agent
pip install -e ".[dev]"

Update

pip install --no-cache-dir --force-reinstall git+https://github.com/KJH-Sun/jupyter-kernel-mcp.git

버전 번호가 동일하면 pip이 캐시를 재사용하므로 --no-cache-dir --force-reinstall 플래그가 필요합니다. 설치 후 Claude Code에서 MCP 서버를 재시작해야 변경사항이 반영됩니다.

Claude Code MCP 서버로 사용

설치 후 프로젝트의 .mcp.json에 추가:

{
  "mcpServers": {
    "notebook-runtime": {
      "command": "notebook-agent-mcp",
      "args": []
    }
  }
}

Claude Code를 (재)시작하면 다음 도구들이 자동으로 사용 가능해집니다:

  • open_notebook — 노트북 열기 + 커널 시작

  • list_cells — 셀 목록 조회

  • run_cell — 단일 셀 실행

  • run_until — 처음부터 N번 셀까지 실행

  • restart_kernel — 커널 재시작

  • list_sessions — 활성 세션 조회

  • get_cell_output — 셀 출력 조회 + 이미지 추출

  • shutdown_idle — 유휴 커널 종료

  • save_notebook — 노트북 저장

Run the FastAPI Server

uvicorn app.main:app --host 127.0.0.1 --port 8000

Use the CLI (no server required)

# Open a notebook (starts kernel)
notebook-agent open --path /path/to/notebook.ipynb

# List cells
notebook-agent list-cells --path /path/to/notebook.ipynb

# Run a single cell (0-based index)
notebook-agent run-cell --path /path/to/notebook.ipynb --cell 0

# Run all cells up to index 5 with fresh kernel
notebook-agent run-until --path /path/to/notebook.ipynb --cell 5 --mode restart_and_run_until

# Restart kernel
notebook-agent restart-kernel --path /path/to/notebook.ipynb

# List active sessions
notebook-agent sessions

# Shutdown idle kernels
notebook-agent shutdown-idle --max-idle 1800

# Read cell outputs and extract images
notebook-agent get-cell-output --path /path/to/notebook.ipynb --cell 3

# Save notebook
notebook-agent save --path /path/to/notebook.ipynb

All CLI commands output structured JSON.

Related MCP server: JupyterMCP

Execution Modes

reuse_existing_session (default)

Reuses the existing kernel session. Variables, imports, and state from prior cell executions are preserved. Fast — only runs the requested cell.

Use when: running cells sequentially in order, or when prior cells have already been executed.

restart_and_run_until

Shuts down the current kernel, starts a fresh one, then runs all code cells from cell 0 through the target cell. Guarantees clean, reproducible state.

Use when:

  • A cell fails with NameError or ImportError (missing prior state)

  • You want to ensure reproducible results

  • The user asks to "run from scratch"

Example Agent Workflow

# 1. Open notebook
notebook-agent open --path analysis.ipynb

# 2. Check cells
notebook-agent list-cells --path analysis.ipynb

# 3. Run cells in order
notebook-agent run-cell --path analysis.ipynb --cell 0
notebook-agent run-cell --path analysis.ipynb --cell 1

# 4. If cell 3 fails with NameError, retry with full state rebuild
notebook-agent run-cell --path analysis.ipynb --cell 3 --mode restart_and_run_until

# 5. Check image outputs from a cell (e.g. matplotlib chart)
notebook-agent get-cell-output --path analysis.ipynb --cell 2
# → image_paths: ["/tmp/notebook-agent/analysis/cell_2_0.png"]

HTTP API

When the FastAPI server is running:

Endpoint

Method

Description

/notebooks/open

POST

Open notebook, start kernel

/notebooks/cells?path=...

GET

List cells

/notebooks/run-cell

POST

Run a single cell

/notebooks/run-until

POST

Run cells 0..N

/notebooks/restart-kernel

POST

Restart kernel

/notebooks/save

POST

Save notebook

/sessions

GET

List active sessions

/sessions/shutdown-idle

POST

Shutdown idle kernels

Architecture

See docs/architecture.md for detailed component design.

Agent Usage Guide

See docs/agent_skill.md for instructions on how an AI agent should use this system.

Tests

pytest

Tests use real Jupyter kernels — requires ipykernel installed.

F
license - not found
-
quality - not tested
C
maintenance

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/KJH-Sun/jupyter-kernel-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server