notebook-agent-mcp
Allows executing Jupyter notebook cells with persistent kernel state, including opening notebooks, running cells, retrieving outputs, and managing sessions.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@notebook-agent-mcpOpen analysis.ipynb and run cell 0"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 8000Use 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.ipynbAll 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
NameErrororImportError(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 |
| POST | Open notebook, start kernel |
| GET | List cells |
| POST | Run a single cell |
| POST | Run cells 0..N |
| POST | Restart kernel |
| POST | Save notebook |
| GET | List active sessions |
| 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
pytestTests use real Jupyter kernels — requires ipykernel installed.
This server cannot be installed
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
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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