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

Enhanced Functions

VS Code Functions

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