jupyter-notebook-mcp

A FastMCP server for loading, editing, searching, and saving Jupyter notebooks (.ipynb) through MCP tools.

The server keeps one notebook open at a time and uses live cell indices that update as cells are inserted or removed.

Features

• Single active notebook session with in-memory state (path, notebook object, dirty flag)

• Autosave current notebook before loading a different notebook

• Real insert/remove semantics: indices shift immediately after edits

• Return full notebook as plain-text blocks when loading

• Save/import notebook content in markdown block format

• Case-insensitive keyword search with contextual snippets

• Actionable ToolError messages for common failure cases

Related MCP server: jupyter-editor-mcp

Tool API

The server exposes the following MCP tools:

• load_notebook(path: str)

  • Loads and validates a notebook

  • Autosaves the currently open notebook first (if any)

  • Returns active cells as plain-text blocks: [index:N type:...] + full content

• save_notebook(path: str | None = None)

  • Saves current notebook (optionally to a new path)

• read_cell(index: int)

  • Returns full source for one active cell

• add_cell(content: str, cell_type: str = "code", index: int | None = None)

  • Appends a new cell when index is omitted

  • Inserts below the referenced cell when index is provided (insert at index + 1)

  • Returns plain-text blocks for changed cell + adjacent cells

• replace_cell(index: int, content: str)

  • Replaces entire cell source

• remove_cell(index: int)

  • Removes a cell by index with immediate reindexing

  • Returns plain-text blocks for changed cell + adjacent cells

• delete_cell(index: int)

  • Backward-compatible alias of remove_cell

• save_markdown(path: str)

  • Saves the same text returned by load_notebook() to a markdown file path

• from_markdown(path: str)

  • Reads exported markdown blocks from disk and replaces current notebook cells

• search_cell(keywords: str)

  • Space-separated keyword search (all keywords must match)

Requirements

• Python >=3.12

• uv for environment and dependency management

MCP Installation

Run directly with uvx (no persistent install):

uvx jupyter-notebook-mcp --from git+https://github.com/g0g5/jupyter-notebook-mcp

Install as a uv tool:

uv tool install jupyter-notebook-mcp --from git+https://github.com/g0g5/jupyter-notebook-mcp

Quick Start

uv sync
uv run python -m jupyter_notebook_mcp

You can also run via the project script entrypoint:

uv run jupyter-notebook-mcp

MCP Client Configuration (stdio)

Use one of the following configurations.

Option 1: run with uvx from GitHub:

{
  "mcpServers": {
    "jupyter-notebook-mcp": {
      "command": "uvx",
      "args": [
        "jupyter-notebook-mcp",
        "--from",
        "git+https://github.com/g0g5/jupyter-notebook-mcp"
      ]
    }
  }
}

Option 2: after uv tool install, run installed command directly:

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

Development

Install/update dependencies:

uv sync

Typecheck (lightweight compile check):

uv run python -m py_compile jupyter_notebook_mcp/*.py tests/*.py

Run tests:

uv run pytest -v

Project Structure

jupyter-notebook-mcp/
|- jupyter_notebook_mcp/
|  |- __main__.py                  # Module entrypoint for `python -m jupyter_notebook_mcp`
|  |- server.py                    # FastMCP app and tool registration
|  |- session.py                   # Shared in-memory notebook session state
|  |- notebook_io.py               # Notebook load/save and validation
|  |- cell_ops.py                  # Cell read/edit operations
|  |- markdown_codec.py            # Markdown export/import parsing
|  |- search.py                    # Keyword search and snippet extraction
|  \- formatting.py                # Cell block and markdown preview formatting
\- tests/
   |- conftest.py                  # Shared fixtures (session reset)
   |- helpers.py                   # Shared notebook test helpers
   |- test_contract_flow.py
   |- test_session_and_io.py
   |- test_cell_editing.py
   |- test_markdown_codec.py
   \- test_search_and_formatting.py

Behavior Notes

• If no notebook is loaded, notebook-dependent tools return:

  • No notebook is loaded. Use load_notebook(path) first.

• Cell indices are always current active indices; insert/remove operations reindex following cells.

• On save, the server validates notebook structure with nbformat.validate before writing.