tofunori/mcp-jupyter-complete
If you are the rightful owner of mcp-jupyter-complete and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
A comprehensive Model Context Protocol (MCP) server for Jupyter notebook manipulation with position-based operations and VS Code integration.
MCP Jupyter Complete
A comprehensive Model Context Protocol (MCP) server for Jupyter notebook manipulation with position-based operations and VS Code integration.
Features
🎯 Position-Based Operations
list_cells
- List all cells with indices and type informationget_cell_source
- Get source code of specific cells by indexedit_cell_source
- Edit cell content by indexinsert_cell
- Insert new cells at specific positionsdelete_cell
- Delete cells by index with automatic reindexing
🚀 Enhanced Operations
move_cell
- Move cells between positionsconvert_cell_type
- Convert between code/markdown/raw cellsbulk_edit_cells
- Perform multiple operations in a single call
🔧 VS Code Integration
trigger_vscode_reload
- Force VS Code to reload notebook files- File watcher support for automatic reloading
- VS Code workspace and settings generation
- Extension recommendations for optimal Jupyter experience
Installation
-
Clone the repository:
git clone https://github.com/tofunori/mcp-jupyter-complete.git cd mcp-jupyter-complete
-
Install dependencies:
npm install
-
Make executable (optional):
npm link
Configuration
Add to your ~/.claude.json
configuration:
{
"mcpServers": {
"jupyter-complete": {
"command": "node",
"args": ["/path/to/mcp-jupyter-complete/src/index.js"]
}
}
}
Or if installed globally via npm:
{
"mcpServers": {
"jupyter-complete": {
"command": "mcp-jupyter-complete"
}
}
}
Usage Examples
Basic Cell Operations
// List all cells
await mcp.call("list_cells", {
notebook_path: "/path/to/notebook.ipynb"
});
// Get cell content
await mcp.call("get_cell_source", {
notebook_path: "/path/to/notebook.ipynb",
cell_index: 0
});
// Edit a cell
await mcp.call("edit_cell_source", {
notebook_path: "/path/to/notebook.ipynb",
cell_index: 1,
new_source: "print('Hello World!')"
});
Advanced Operations
// Insert a new markdown cell
await mcp.call("insert_cell", {
notebook_path: "/path/to/notebook.ipynb",
position: 2,
cell_type: "markdown",
source: "# New Section\\n\\nThis is a new markdown cell."
});
// Move a cell
await mcp.call("move_cell", {
notebook_path: "/path/to/notebook.ipynb",
from_index: 3,
to_index: 1
});
// Bulk operations
await mcp.call("bulk_edit_cells", {
notebook_path: "/path/to/notebook.ipynb",
operations: [
{
type: "edit",
cell_index: 0,
new_source: "# Updated title"
},
{
type: "convert",
cell_index: 1,
new_type: "markdown"
}
]
});
VS Code Integration
// Trigger VS Code reload
await mcp.call("trigger_vscode_reload", {
notebook_path: "/path/to/notebook.ipynb"
});
VS Code Setup
For optimal VS Code integration:
-
Install recommended extensions:
- Python
- Jupyter
- Jupyter Keymap
- Jupyter Renderers
-
Configure auto-reload: Add to VS Code settings:
{ "files.watcherExclude": { "**/.ipynb_checkpoints/**": true }, "notebook.diffEditor.ignoreTrimWhitespace": false }
-
Use with Claude Code: When using with Claude Code, notebook changes made via MCP will automatically trigger VS Code to prompt for reload.
API Reference
Core Functions
Function | Parameters | Description |
---|---|---|
list_cells | notebook_path | Lists all cells with indices |
get_cell_source | notebook_path , cell_index | Gets cell source code |
edit_cell_source | notebook_path , cell_index , new_source | Edits cell content |
insert_cell | notebook_path , position , cell_type? , source? | Inserts new cell |
delete_cell | notebook_path , cell_index | Deletes cell |
Enhanced Functions
Function | Parameters | Description |
---|---|---|
move_cell | notebook_path , from_index , to_index | Moves cell position |
convert_cell_type | notebook_path , cell_index , new_type | Converts cell type |
bulk_edit_cells | notebook_path , operations[] | Bulk operations |
VS Code Functions
Function | Parameters | Description |
---|---|---|
trigger_vscode_reload | notebook_path | Forces VS Code reload |
Cell Types
Supported cell types:
code
- Python/executable code cellsmarkdown
- Markdown text cellsraw
- Raw text cells
Error Handling
The server provides detailed error messages for:
- Invalid cell indices
- File read/write permissions
- Malformed notebook JSON
- Invalid cell type conversions
Development
Testing
npm test
Linting
npm run lint
Development Mode
npm run dev
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
License
MIT License - see file for details.
Changelog
v1.0.0
- Initial release
- Position-based cell operations
- VS Code integration
- Bulk operations support
- Comprehensive error handling