MCP Jupyter Complete Server

You can manipulate Jupyter notebooks remotely through a dedicated MCP server that offers position-based cell operations, enhanced editing features, and seamless VS Code integration. This server lets you list, read, edit, insert, delete, move, and convert cells, plus trigger VS Code reloads for a smooth notebook editing workflow.

How to use

You interact with the MCP server from your MCP client by calling a set of core and advanced functions. Use the core functions to inspect and modify cells by index, and use the enhanced functions to move cells, bulk edit, or convert cell types. For VS Code workflows, you can trigger a reload to refresh open notebooks.

Core capabilities include listing all cells with their indices and types, retrieving a cell’s source, editing a cell’s content, inserting new cells at a specific position, and deleting cells with automatic reindexing.

Advanced capabilities allow you to move cells between positions, convert a cell’s type (code, markdown, or raw), and perform multiple edits in a single call. If you’re integrating with VS Code, you can force a reload of notebook files to reflect changes immediately.

Practical usage patterns you can apply now include: listing cells to map notebook structure, editing specific cells to update content, inserting new cells to add notes or explanations, moving cells to reorganize sections, and bulk-editing several cells for a quick, coordinated update.

How to install

# Prerequisites
# - Node.js and npm must be installed on your system
node -v
npm -v

# Option A: Set up from source
# 1) Clone the MCP server 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 snippet (local run via node)
"""
{
  "mcpServers": {
    "jupyter-complete": {
      "command": "node",
      "args": ["/path/to/mcp-jupyter-complete/src/index.js"]
    }
  }
}
"""

# Start the server (example using the local script)
node /path/to/mcp-jupyter-complete/src/index.js

# Option B: Install and run globally if you prefer npm install -g style
# 1) Install globally (from the same project context or published package)
npm install -g mcp-jupyter-complete

# 2) Start via the global command (no local path required)
mcp-jupyter-complete

Configuration

Configure the MCP server in your user configuration to point to the running server. You can run either of the following configurations depending on how you install the server.

{
  "mcpServers": {
    "jupyter-complete": {
      "command": "node",
      "args": ["/path/to/mcp-jupyter-complete/src/index.js"]
    }
  }
}

Notes on installation and usage

If you install globally via npm, you can omit the path to the local script and use the global command instead.

VS Code integration and notebook reloads

To keep your notebook workspace in sync, you can trigger a VS Code reload after making changes through MCP. This ensures the editor reflects the latest notebook state.

Troubleshooting

If you encounter file permission errors, verify that your user has read/write access to the notebook files you are editing. If a notebook JSON is malformed, correct the JSON structure before retrying the operation. For invalid cell indices, double-check the target cell index against the current notebook cell list.

Security and access

Limit access to the MCP server to trusted clients or internal networks. Use appropriate authentication and avoid exposing the server to untrusted users. Regularly review your notebook file permissions and monitor for unusual edits.

Available tools

list_cells

List all cells with indices and type information for the specified notebook path.

get_cell_source

Retrieve the source code of a specific cell by its index in the given notebook.

edit_cell_source

Edit the source of a specific cell identified by its index in the notebook.

insert_cell

Insert a new cell at a given position with a specified cell type and content.

delete_cell

Delete a cell by index and automatically reindex the remaining cells.

move_cell

Move a cell from one index to another within the notebook.

convert_cell_type

Convert a cell between code, markdown, and raw types.

bulk_edit_cells

Execute multiple cell operations in a single request, such as edits, inserts, and type conversions.

trigger_vscode_reload

Force Visual Studio Code to reload the notebook to reflect changes.