F
licenseNot graded
qualityD
maintenanceA Model Control Protocol (MCP) server that enables remote programmatic control of Jupyter notebooks, allowing AI assistants and applications to create, edit, and execute notebook cells via SSE protocol.
-
jupyter-editor-mcp
by jsamuel1
You can programmatically inspect, edit, organize, merge/split, search, validate, and manage metadata/outputs of Jupyter notebooks via file-based tools—no Jupyter server needed.
Read notebooks: summarize structure, list/get cells, search cell contents.
Modify cells: replace, insert, append, delete, and substring-replace cell content.
Manage metadata/kernels: get/update notebook or cell metadata, set kernels, list common kernel configs.
Batch edit: replace/delete/insert multiple cells, regex search-and-replace, reorder, filter cells.
Multi-notebook operations: merge, split, apply operations across notebooks, search across notebooks, sync metadata, extract cells, clear outputs.
Validate/inspect: validate one or many notebooks and get notebook summaries/info.
Provides tools for reading, modifying, and batch editing Jupyter notebook files (.ipynb) including cell operations, metadata management, and notebook validation, without requiring a running Jupyter server.
Click on "Deploy 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., "@jupyter-editor-mcp Insert a markdown cell at the top with a title"
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.
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
Related MCP server: notebook-editor
Installation
One-Click Install
From PyPI
uv tool install jupyter-editor-mcp
jupyter-editor-mcpFrom Source
git clone https://github.com/jsamuel1/jupyter-editor-mcp.git
cd jupyter-editor-mcp
uv sync --extra devSee INSTALL.md for detailed configuration options.
As a Kiro Power (Agent Plugin)
The power/ directory is an Agent Plugins 1.0.0 package, the format Kiro powers use:
power/
├── plugin.json # manifest (name, version, author, keywords)
├── mcp.json # runs `uvx jupyter-editor-mcp` over stdio
└── skills/
└── notebook-editing/
└── SKILL.md # tool guide, workflows, safety boundariesIn Kiro: Powers panel → Add Custom Power → Import power from GitHub and enter https://github.com/jsamuel1/jupyter-editor-mcp, or clone the repository and use Import power from a folder with the power/ directory. See INSTALL.md for tool-approval settings.
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 sync --extra devDocumentation
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
Available Tools
29 toolsipynb_append_cellA
Append cell to end of a Jupyter Notebook (.ipynb).
Args: ipynb_filepath: Path to Jupyter Notebook (.ipynb) file (absolute path preferred) content: Cell content (provide as raw string, no additional escaping needed) cell_type: Type of cell ('code', 'markdown', 'raw')
Returns: Dict with 'success' and 'cell_index' or 'error' key (0-based index of new cell)
Inputs: content (required), ipynb_filepath (required), cell_type. Returns: object
ipynb_apply_to_notebooksA
Apply same operation to multiple Jupyter Notebooks (.ipynb).
Args: ipynb_filepaths: List of notebook paths (absolute paths preferred) operation: Operation name ('set_kernel', 'clear_outputs', 'update_metadata') operation_params: Parameters for the operation as a dictionary
Returns: Dict with 'success' and 'results' or 'error' key
Inputs: operation (required), ipynb_filepaths (required), operation_params. Returns: object
ipynb_clear_outputsA
Clear all outputs from code cells in one or more Jupyter Notebooks (.ipynb).
Args: ipynb_filepaths: Single filepath or list of filepaths (absolute paths preferred)
Returns: Dict with 'success' and 'notebooks_processed' or 'error' key
Inputs: ipynb_filepaths (required). Returns: object
ipynb_delete_cellA
Delete cell at specified index in a Jupyter Notebook (.ipynb).
Args: ipynb_filepath: Path to Jupyter Notebook (.ipynb) file (absolute path preferred) cell_index: Index of cell to delete (0-based indexing)
Returns: Dict with 'success' and 'new_cell_count' or 'error' key
Note: Indices of cells after the deleted cell will shift by -1
Inputs: cell_index (required), ipynb_filepath (required). Returns: object
ipynb_delete_cells_batchA
Delete multiple cells by indices from a Jupyter Notebook (.ipynb).
Args: ipynb_filepath: Path to Jupyter Notebook (.ipynb) file (absolute path preferred) cell_indices: List of cell indices to delete (0-based indexing)
Returns: Dict with 'success', 'cells_deleted', 'new_cell_count' or 'error' key
Note: Deletions are processed in descending order to maintain index validity. Provide indices as they appear before any deletions occur.
Inputs: cell_indices (required), ipynb_filepath (required). Returns: object
ipynb_extract_cellsA
Extract matching cells from multiple Jupyter Notebooks (.ipynb) into a new notebook.
Args: output_ipynb_filepath: Path for output notebook (absolute path preferred) input_ipynb_filepaths: List of source notebook paths (absolute paths preferred) pattern: Optional regex pattern to match cell_type: Optional cell type filter
Returns: Dict with 'success', 'cells_extracted', 'source_notebooks' or 'error' key
Inputs: input_ipynb_filepaths (required), output_ipynb_filepath (required), pattern, cell_type. Returns: object
ipynb_filter_cellsB
Keep only cells matching criteria in a Jupyter Notebook (.ipynb), delete others.
Args: ipynb_filepath: Path to Jupyter Notebook (.ipynb) file (absolute path preferred) cell_type: Optional filter by cell type pattern: Optional regex pattern to match
Returns: Dict with 'success', 'cells_kept' or 'error' key
Inputs: ipynb_filepath (required), pattern, cell_type. Returns: object
ipynb_get_cellA
Get content of a specific cell by index from a Jupyter Notebook (.ipynb).
Args: ipynb_filepath: Path to Jupyter Notebook (.ipynb) file (absolute path preferred) cell_index: Index of cell (supports negative indexing)
Returns: Dict with 'content' or 'error' key
Inputs: cell_index (required), ipynb_filepath (required). Returns: object
ipynb_get_metadataA
Get Jupyter Notebook (.ipynb) or cell metadata.
Args: ipynb_filepath: Path to Jupyter Notebook (.ipynb) file (absolute path preferred) cell_index: Index of cell (None for notebook metadata)
Returns: Metadata dictionary or dict with 'error' key
Inputs: ipynb_filepath (required), cell_index. Returns: object
ipynb_get_notebook_infoA
Get summary information about a Jupyter Notebook (.ipynb).
Args: ipynb_filepath: Path to Jupyter Notebook (.ipynb) file (absolute path preferred)
Returns: Dict with cell_count, cell_types, kernel, format_version, file_size or 'error' key
Inputs: ipynb_filepath (required). Returns: object
ipynb_insert_cellA
Insert new cell at specified position in a Jupyter Notebook (.ipynb).
Args: ipynb_filepath: Path to Jupyter Notebook (.ipynb) file (absolute path preferred) cell_index: Position to insert cell (0-based indexing) content: Cell content (provide as raw string, no additional escaping needed) cell_type: Type of cell ('code', 'markdown', 'raw')
Returns: Dict with 'success' and 'new_cell_count' or 'error' key
Note: Indices of cells at or after the insertion point will shift by +1
Inputs: content (required), cell_index (required), ipynb_filepath (required), cell_type. Returns: object
ipynb_insert_cells_batchA
Insert multiple cells at specified positions in a Jupyter Notebook (.ipynb).
Args: ipynb_filepath: Path to Jupyter Notebook (.ipynb) file (absolute path preferred) insertions: List of dicts with 'cell_index', 'content', 'cell_type' keys (provide content as raw strings, no additional escaping needed)
Returns: Dict with 'success' and 'cells_inserted' or 'error' key
Note: Uses 0-based indexing. Insertions are processed in order, so later indices will be affected by earlier insertions. Consider sorting by index descending to maintain intended positions.
Inputs: insertions (required), ipynb_filepath (required). Returns: object
ipynb_list_available_kernelsB
List common Jupyter Notebook kernel configurations.
Returns: Dict with 'kernels' list
Inputs: no named parameters. Returns: object
ipynb_list_cellsA
List all cells in a Jupyter Notebook (.ipynb) with indices, types, and content previews.
Args: ipynb_filepath: Path to Jupyter Notebook (.ipynb) file (absolute path preferred)
Returns: Dict with 'cells' list or 'error' key on failure
Inputs: ipynb_filepath (required). Returns: object
ipynb_merge_notebooksA
Merge multiple Jupyter Notebooks (.ipynb) into one.
Args: output_ipynb_filepath: Path for merged notebook (absolute path preferred) input_ipynb_filepaths: List of notebook paths to merge (absolute paths preferred) add_separators: Whether to add separator cells between notebooks
Returns: Dict with 'success', 'total_cells', 'notebooks_merged' or 'error' key
Inputs: input_ipynb_filepaths (required), output_ipynb_filepath (required), add_separators. Returns: object
ipynb_read_notebookA
Read a Jupyter Notebook (.ipynb) and return structure summary.
Args: ipynb_filepath: Path to Jupyter Notebook (.ipynb) file (absolute path preferred)
Returns: Dictionary with cell_count, cell_types, kernel_info, format_version or dict with 'error' key on failure
Inputs: ipynb_filepath (required). Returns: object
ipynb_reorder_cellsA
Reorder cells in a Jupyter Notebook (.ipynb) by providing new index mapping.
Args: ipynb_filepath: Path to Jupyter Notebook (.ipynb) file (absolute path preferred) new_order: List of indices in desired order (0-based indexing)
Returns: Dict with 'success' or 'error' key
Inputs: new_order (required), ipynb_filepath (required). Returns: object
ipynb_replace_cellA
Replace entire cell content in a Jupyter Notebook (.ipynb).
Args: ipynb_filepath: Path to Jupyter Notebook (.ipynb) file (absolute path preferred) cell_index: Index of cell to replace new_content: New content for cell (provide as raw string, no additional escaping needed)
Returns: Dict with 'success' or 'error' key
Inputs: cell_index (required), new_content (required), ipynb_filepath (required). Returns: object
ipynb_replace_cells_batchA
Replace multiple cells in one operation in a Jupyter Notebook (.ipynb).
Args: ipynb_filepath: Path to Jupyter Notebook (.ipynb) file (absolute path preferred) replacements: List of dicts with 'cell_index' and 'content' keys (provide content as raw strings, no additional escaping needed)
Returns: Dict with 'success' and 'cells_modified' or 'error' key
Inputs: replacements (required), ipynb_filepath (required). Returns: object
ipynb_search_cellsA
Search for pattern in cell content of a Jupyter Notebook (.ipynb).
Args: ipynb_filepath: Path to Jupyter Notebook (.ipynb) file (absolute path preferred) pattern: Search pattern (regex supported) case_sensitive: Whether search is case-sensitive (default: False)
Returns: Dict with 'results' list or 'error' key
Inputs: pattern (required), ipynb_filepath (required), case_sensitive. Returns: object
ipynb_search_notebooksA
Search across multiple Jupyter Notebooks (.ipynb).
Args: ipynb_filepaths: List of notebook paths (absolute paths preferred) pattern: Search pattern (regex) return_context: Whether to include context
Returns: Dict with 'results' and 'match_count' or 'error' key
Inputs: pattern (required), ipynb_filepaths (required), return_context. Returns: object
ipynb_search_replace_allA
Search and replace across all cells in a Jupyter Notebook (.ipynb).
Args: ipynb_filepath: Path to Jupyter Notebook (.ipynb) file (absolute path preferred) pattern: Pattern to search for (regex) replacement: Replacement string cell_type: Optional filter by cell type
Returns: Dict with 'success' and 'replacements_made' or 'error' key
Inputs: pattern (required), replacement (required), ipynb_filepath (required), cell_type. Returns: object
ipynb_set_kernelB
Set kernel specification for a Jupyter Notebook (.ipynb).
Args: ipynb_filepath: Path to Jupyter Notebook (.ipynb) file (absolute path preferred) kernel_name: Kernel name (e.g., 'python3') display_name: Display name (e.g., 'Python 3') language: Programming language (default: 'python')
Returns: Dict with 'success' or 'error' key
Inputs: kernel_name (required), display_name (required), ipynb_filepath (required), language. Returns: object
ipynb_split_notebookA
Split a Jupyter Notebook (.ipynb) into multiple files by criteria.
Args: ipynb_filepath: Path to Jupyter Notebook (.ipynb) file (absolute path preferred) output_dir: Directory for output files split_by: Split criteria ('markdown_headers' or 'cell_count')
Returns: Dict with 'success' and 'files_created' or 'error' key
Inputs: output_dir (required), ipynb_filepath (required), split_by. Returns: object
ipynb_str_replace_in_cellA
Replace substring within cell content in a Jupyter Notebook (.ipynb).
Args: ipynb_filepath: Path to Jupyter Notebook (.ipynb) file (absolute path preferred) cell_index: Index of cell old_str: String to replace (provide as raw string, no additional escaping needed) new_str: Replacement string (provide as raw string, no additional escaping needed)
Returns: Dict with 'success' or 'error' key
Inputs: new_str (required), old_str (required), cell_index (required), ipynb_filepath (required). Returns: object
ipynb_sync_metadataB
Synchronize metadata across multiple Jupyter Notebooks (.ipynb).
Args: ipynb_filepaths: List of notebook paths (absolute paths preferred) metadata: Metadata to apply merge: Whether to merge with existing metadata
Returns: Dict with 'success' and 'notebooks_updated' or 'error' key
Inputs: metadata (required), ipynb_filepaths (required), merge. Returns: object
ipynb_update_metadataA
Update Jupyter Notebook (.ipynb) or cell metadata.
Args: ipynb_filepath: Path to Jupyter Notebook (.ipynb) file (absolute path preferred) metadata: Metadata dictionary to merge cell_index: Index of cell (None for notebook metadata)
Returns: Dict with 'success' or 'error' key
Inputs: metadata (required), ipynb_filepath (required), cell_index. Returns: object
ipynb_validate_notebookA
Validate Jupyter Notebook (.ipynb) structure.
Args: ipynb_filepath: Path to Jupyter Notebook (.ipynb) file (absolute path preferred)
Returns: Dict with 'valid' boolean and optional 'errors' list
Inputs: ipynb_filepath (required). Returns: object
ipynb_validate_notebooks_batchA
Validate multiple Jupyter Notebooks (.ipynb).
Args: ipynb_filepaths: List of notebook paths (absolute paths preferred)
Returns: Dict with 'results' mapping filepath to validation status
Inputs: ipynb_filepaths (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
A3.6/5.0
Scored across 29 tools
Disambiguation3/5
Most tools have clear boundaries, but there is notable overlap: ipynb_read_notebook and ipynb_get_notebook_info both return nearly identical notebook summaries, and ipynb_apply_to_notebooks duplicates operations already available via dedicated tools (e.g., set_kernel, clear_outputs, update_metadata). Batch vs single versions are distinct but admirably named.
Naming Consistency5/5
All tool names follow a consistent ipynb_ verb_noun pattern, with descriptive verbs like list, get, insert, delete, replace, merge, validate. Even compound verbs like str_replace and search_replace are clear and predictable, and batch variants consistently append '_batch'.
Tool Count2/5
At 29 tools, this exceeds the 'too many (25+)' threshold. While the domain is rich, the count feels bloated due to the inclusion of both single and batch versions of many operations, plus near-duplicate read/info tools. A leaner set around 20 would be more appropriate.
Completeness4/5
The tool set covers cell CRUD, notebook metadata, kernel settings, validation, searching, and multi-notebook operations like merge, split, and batch processing. Minor gaps exist, such as no explicit 'create new notebook' tool, but agents can work around this via merge or extract flows.
Maintenance
ActivityMaintained
ResponsivenessOutdated data
Related MCP Connectors
Hosted MCP server for AI photo editing: nothing to install, no desktop photo editor needed.
A MCP server built for developers enabling Git based project management with project and personal…
MCP registry & directory: search, find & install 31k+ MCP servers & tools. Catalog and marketplace.
MCP Server for JFrog, providing tools for development and artifact management.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceA local MCP server for reading, writing, and executing Jupyter notebooks using jupyter_client for direct kernel communication.-
- AlicenseNot gradedqualityDmaintenanceMCP server for Jupyter notebook navigation and editing. Reads .ipynb files directly as JSON, providing efficient tools for reading, searching, and modifying cells without needing a Jupyter server.MIT
- AlicenseBqualityDmaintenanceAn MCP server that connects directly to a Jupyter kernel via ZMQ, enabling AI assistants to read, create, edit, execute, and manage Jupyter Notebooks as MCP tools.9MIT