Jupyter Notebook Editor MCP Server

A Model Context Protocol (MCP) server for programmatically editing Jupyter notebooks while preserving their format and structure.

Features

• 29 specialized tools for notebook manipulation
• File-based operations - no Jupyter server required
• Format preservation - automatic validation after modifications
• Batch operations - modify multiple cells or notebooks at once
• Type-safe - full type hints for all operations

Installation

One-Click Install

From PyPI

uv tool install jupyter-editor-mcp
jupyter-editor-mcp

From Source

git clone https://github.com/jsamuel1/jupyter-editor-mcp.git
cd jupyter-editor-mcp
uv venv
uv pip install -e ".[dev]"

See INSTALL.md for detailed configuration options.

Usage

With Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "jupyter-editor": {
      "command": "jupyter-editor-mcp"
    }
  }
}

Example Interactions

Read a notebook:

"Show me the structure of my notebook.ipynb"

Insert a cell:

"Add a markdown cell at the beginning explaining what this notebook does"

Batch operations:

"Replace all occurrences of 'old_function' with 'new_function' in all code cells"

Multi-notebook:

"Merge analysis.ipynb and visualization.ipynb into combined.ipynb"

Tool Categories

• Read Operations (4 tools): read_notebook, list_cells, get_cell, search_cells
• Cell Modification (5 tools): replace_cell, insert_cell, append_cell, delete_cell, str_replace_in_cell
• Metadata Operations (4 tools): get_metadata, update_metadata, set_kernel, list_available_kernels
• Batch Operations - Multi-Cell (6 tools): replace_cells_batch, delete_cells_batch, insert_cells_batch, search_replace_all, reorder_cells, filter_cells
• Batch Operations - Multi-Notebook (7 tools): merge_notebooks, split_notebook, apply_to_notebooks, search_notebooks, sync_metadata, extract_cells, clear_outputs
• Validation (3 tools): validate_notebook, get_notebook_info, validate_notebooks_batch

Development

# Run tests
pytest

# Run tests with coverage
pytest --cov

# Install in development mode
uv pip install -e ".[dev]"

Documentation

• docs/RESEARCH.md - Technical research and tool specifications
• docs/REQUIREMENTS.md - User stories and acceptance criteria
• docs/DESIGN.md - Architecture and API design
• CONTRIBUTING.md - Contribution guidelines

License

MIT