Skip to main content
Glama
Claude Code Notebook MCP

Claude Code Notebook MCP

by mstampfer

Claude Code Notebook MCP

GitHub stars GitHub forks GitHub downloads

A Model Context Protocol (MCP) server that provides comprehensive Jupyter notebook interaction capabilities, compatible with Claude Code.

Note: This library emulates the functionality of the cursor-notebook-mcp repository but runs in a web browser. For live updates in Jupyter, install the collaboration extension:

pip install jupyter-collaboration
jupyter labextension install @jupyter/collaboration-extension

Or for JupyterLab 3.x:

pip install jupyterlab-collaboration

Features

This MCP server implements all 29 required Jupyter notebook operations:

Notebook Management

  • notebook_create - Creates a new, empty notebook file

  • notebook_delete - Deletes an existing notebook file

  • notebook_rename - Renames/moves a notebook file from one path to another

  • notebook_read - Reads an entire notebook and returns its structure as a dictionary

Cell Operations

  • notebook_read_cell - Reads the source content of a specific cell

  • notebook_add_cell - Adds a new code or markdown cell after a specified index

  • notebook_edit_cell - Replaces the source content of a specific cell

  • notebook_delete_cell - Deletes a specific cell

  • notebook_change_cell_type - Changes a cell's type (code, markdown, or raw)

  • notebook_duplicate_cell - Duplicates a cell multiple times (default: once)

  • notebook_move_cell - Moves a cell to a different position

  • notebook_split_cell - Splits a cell into two at a specified line number

  • notebook_merge_cells - Merges a cell with the cell immediately following it

Cell Content & Metadata

  • notebook_read_cell_metadata - Reads the metadata of a specific cell

  • notebook_edit_cell_metadata - Updates the metadata of a specific cell

  • notebook_read_cell_output - Reads the output list of a specific code cell

  • notebook_edit_cell_output - Allows direct manipulation and setting of cell outputs

  • notebook_clear_cell_outputs - Clears the outputs and execution count of a specific cell

  • notebook_clear_all_outputs - Clears outputs and execution counts for all code cells

Notebook Information & Metadata

  • notebook_get_cell_count - Returns the total number of cells

  • notebook_read_metadata - Reads the top-level notebook metadata

  • notebook_edit_metadata - Updates the top-level notebook metadata

  • notebook_get_info - Retrieves general information (cell count, metadata, kernel, language info)

  • notebook_validate - Validates the notebook structure against the nbformat schema

Advanced Operations

  • notebook_export - Exports the notebook to another format (e.g., python, html) using nbconvert

  • notebook_get_outline - Produces an outline showing cell numbers with major headings/functions and line counts

  • notebook_search - Searches cells for a keyword, showing which cell matches were found with contextual snippets

  • notebook_bulk_add_cells - Adds multiple cells to a notebook in a single operation

  • notebook_get_server_path_context - Provides detailed server path configuration

Related MCP server: JupyterMCP

Installation

npm install

Usage

As MCP Server (for Claude Code)

  1. Navigate to the project directory:

cd /path/to/claude-code-notebook-mcp
  1. Add the MCP server:

claude mcp add jupyter "$(pwd)/src/server.js"
  1. Verify the server was added:

claude mcp list

Option 2: Manual Configuration

  1. Copy the example configuration file and customize it:

# For project-specific configuration
cp .mcp.example.json .mcp.json

# Or for Claude Code configuration
cp claude-code-config.example.json claude-code-config.json
  1. Edit the configuration file and update the cwd path to your project location:

{
  "mcpServers": {
    "jupyter": {
      "command": "node",
      "args": ["src/server.js"],
      "cwd": "/your/actual/path/to/claude-code-notebook-mcp"
    }
  }
}
  1. For user-wide settings, add to ~/.claude/settings.json:

{
  "mcpServers": {
    "jupyter": {
      "command": "node",
      "args": ["src/server.js"],
      "cwd": "/path/to/claude-code-notebook-mcp"
    }
  }
}
  1. Start Claude Code and the Jupyter tools will be available.

Standalone Client

node src/client.js

This will run a demonstration showing the basic capabilities.

Programmatic Usage

import { JupyterMCPClient } from './src/client.js';

const client = new JupyterMCPClient();
await client.connect();

// Create a new notebook
await client.createNotebook('./my_notebook.ipynb');

// Add a markdown cell
await client.addCell('./my_notebook.ipynb', 'markdown', '# My Notebook', -1);

// Add a code cell
await client.addCell('./my_notebook.ipynb', 'code', 'print("Hello World")', 0);

// Get notebook outline
const outline = await client.getOutline('./my_notebook.ipynb');
console.log(outline.content[0].text);

Compatibility

  • Claude Code: Fully compatible with Claude Code's MCP integration

  • Node.js: Requires Node.js 18+ with ES modules support

  • Jupyter: Compatible with nbformat 4.x notebooks

Development

Running the Server

npm start

Development Mode (with file watching)

npm run dev

Testing

node src/client.js

Architecture

  • Server (src/server.js): MCP server implementation with all 29 Jupyter notebook tools

  • Client (src/client.js): Example client with convenience methods for common operations

  • Configuration (claude-code-config.json): Claude Code MCP server configuration

The server uses the official MCP SDK and implements the full MCP protocol for tool calling. All notebook operations are performed using Node.js file system operations and JSON manipulation, ensuring compatibility across platforms.

Available Tools

29 tools
notebook_add_cellA

Adds a new code or markdown cell after a specified index

Inputs: path (required), index (required), source (required), cell_type (required).

notebook_bulk_add_cellsC

Adds multiple cells to a notebook in a single operation

Inputs: path (required), cells (required), index (required).

notebook_change_cell_typeB

Changes a cell's type (code, markdown, or raw)

Inputs: path (required), new_type (required), cell_index (required).

notebook_clear_all_outputsB

Clears outputs and execution counts for all code cells

Inputs: path (required).

notebook_clear_cell_outputsA

Clears the outputs and execution count of a specific cell

Inputs: path (required), cell_index (required).

notebook_createA

Creates a new, empty notebook file

Inputs: path (required).

notebook_deleteC

Deletes an existing notebook file

Inputs: path (required).

notebook_delete_cellC

Deletes a specific cell

Inputs: path (required), cell_index (required).

notebook_duplicate_cellB

Duplicates a cell multiple times (default: once)

Inputs: path (required), cell_index (required), count.

notebook_edit_cellC

Replaces the source content of a specific cell

Inputs: path (required), cell_index (required), new_source (required).

notebook_edit_cell_metadataC

Updates the metadata of a specific cell

Inputs: path (required), metadata (required), cell_index (required).

notebook_edit_cell_outputC

Allows direct manipulation and setting of cell outputs

Inputs: path (required), outputs (required), cell_index (required).

notebook_edit_metadataC

Updates the top-level notebook metadata

Inputs: path (required), metadata (required).

notebook_exportA

Exports the notebook to another format (e.g., python, html) using nbconvert

Inputs: path (required), format (required), output_path.

notebook_get_cell_countB

Returns the total number of cells

Inputs: path (required).

notebook_get_infoB

Retrieves general information (cell count, metadata, kernel, language info)

Inputs: path (required).

notebook_get_outlineB

Produces an outline showing cell numbers with major headings/functions and line counts

Inputs: path (required).

notebook_get_server_path_contextB

Provides detailed server path configuration (allowed_roots, OS path style, project directory validation, and path construction guidance)

Inputs: path (required).

notebook_merge_cellsB

Merges a cell with the cell immediately following it

Inputs: path (required), cell_index (required).

notebook_move_cellC

Moves a cell to a different position

Inputs: path (required), to_index (required), from_index (required).

notebook_readC

Reads an entire notebook and returns its structure as a dictionary

Inputs: path (required).

notebook_read_cellB

Reads the source content of a specific cell

Inputs: path (required), cell_index (required).

notebook_read_cell_metadataC

Reads the metadata of a specific cell

Inputs: path (required), cell_index (required).

notebook_read_cell_outputB

Reads the output list of a specific code cell

Inputs: path (required), cell_index (required).

notebook_read_metadataA

Reads the top-level notebook metadata

Inputs: path (required).

notebook_renameB

Renames/moves a notebook file from one path to another

Inputs: new_path (required), old_path (required).

notebook_split_cellB

Splits a cell into two at a specified line number

Inputs: path (required), cell_index (required), line_number (required).

notebook_validateB

Validates the notebook structure against the nbformat schema

Inputs: path (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 29 tools

    Disambiguation5/5

    Every tool targets a distinct aspect of notebook manipulation: whole notebook, individual cells, metadata, outputs, or file operations. There is no overlap; even similar-sounding tools like notebook_read and notebook_read_cell are clearly differentiated by scope.

    Naming Consistency5/5

    All tools follow the consistent pattern 'notebook_verb_noun', with verbs like create, delete, read, edit, and nouns like cell, metadata, output. The few plural nouns (cells, outputs) are grammatically correct and do not break the pattern.

    Tool Count2/5

    With 29 tools, the set is beyond the typical 3-15 well-scoped range and exceeds the 25+ threshold for 'too many'. While each tool is justified, the count feels heavy for a notebook manipulation server, and some tools (e.g., notebook_edit_cell_output vs notebook_edit_cell) could be consolidated.

    Completeness5/5

    The tool set covers all major notebook lifecycle operations: CRUD for notebooks and cells, metadata editing, output management, validation, export, search, and outline generation. There are no obvious gaps for the intended domain of notebook file manipulation.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      F
      maintenance
      A Model Context Protocol server that enables AI assistants like Claude to perform Python development tasks through file operations, code analysis, project management, and safe code execution.
      9
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A 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.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that connects to existing IPython kernels, allowing Claude to execute code in a shared persistent environment with your IDE.
      187 PyPI
      2
      MIT