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 information
• get_cell_source - Get source code of specific cells by index
• edit_cell_source - Edit cell content by index
• insert_cell - Insert new cells at specific positions
• delete_cell - Delete cells by index with automatic reindexing

🚀 Enhanced Operations

• move_cell - Move cells between positions
• convert_cell_type - Convert between code/markdown/raw cells
• bulk_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

1. Clone the repository:

   git clone https://github.com/tofunori/mcp-jupyter-complete.git
   cd mcp-jupyter-complete

2. Install dependencies:

   npm install

3. 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:

1. Install recommended extensions:

   • Python
   • Jupyter
   • Jupyter Keymap
   • Jupyter Renderers

2. Configure auto-reload: Add to VS Code settings:

   {
     "files.watcherExclude": {
       "**/.ipynb_checkpoints/**": true
     },
     "notebook.diffEditor.ignoreTrimWhitespace": false
   }

3. 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 cells
• markdown - Markdown text cells
• raw - 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

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Changelog

v1.0.0

• Initial release
• Position-based cell operations
• VS Code integration
• Bulk operations support
• Comprehensive error handling