Jupyter Notebook

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

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.