Jupyter MCP Server

v1.29.0

Connect

Add to your MCP client configuration:

{ "mcpServers": { "Jupyter MCP Server": { "command": "jupyter-mcp-server", "args": [ "--transport", "stdio", "--start-new-code-sandbox", "false" ] } } }

Protocol MCP 2025-11-25Transport stdioCapabilities tools, resources, prompts

Tools

list_files

read-only

TOOLlist_files

List all files and directories recursively in the Jupyter server's file system. Used to explore the file system structure of the Jupyter server or to find specific files or directories.

Parameters

pathstringargument

The starting path to list from (empty string means root directory)

max_depthinteger[0, 3]1argument

Maximum depth to recurse into subdirectories

start_indexinteger>= 00argument

Starting index for pagination (0-based)

limitinteger>= 025argument

Maximum number of items to return (0 means no limit)

patternstringargument

Glob pattern to filter file paths

Returns

resultstringrequired

Tab-separated table with columns: Path, Type, Size, Last_Modified. Includes pagination info header.

list_files

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "list_files",
    "arguments": {
        "path": "",
        "max_depth": 1,
        "start_index": 0,
        "limit": 25,
        "pattern": ""
      }
  }
}

const result = await client.callTool("list_files", {
  "path": "",
  "max_depth": 1,
  "start_index": 0,
  "limit": 25,
  "pattern": ""
});

result = await session.call_tool("list_files", arguments={
  "path": "",
  "max_depth": 1,
  "start_index": 0,
  "limit": 25,
  "pattern": ""
})

Response

{
  "result": "string"
}

list_files

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "list_files",
    "arguments": {
        "path": "",
        "max_depth": 1,
        "start_index": 0,
        "limit": 25,
        "pattern": ""
      }
  }
}

const result = await client.callTool("list_files", {
  "path": "",
  "max_depth": 1,
  "start_index": 0,
  "limit": 25,
  "pattern": ""
});

result = await session.call_tool("list_files", arguments={
  "path": "",
  "max_depth": 1,
  "start_index": 0,
  "limit": 25,
  "pattern": ""
})

Response

{
  "result": "string"
}

list_kernels

read-only

TOOLlist_kernels

List all available kernels in the Jupyter server.

This tool shows all running and available kernel sessions on the Jupyter server, including their IDs, names, states, connection information, and kernel specifications. Useful for monitoring kernel resources and identifying specific kernels for connection.

Returns

resultstringrequired

Tab-separated table with columns: ID, Name, Display_Name, Language, State, Connections, Last_Activity, Environment

list_kernels

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "list_kernels",
    "arguments": {}
  }
}

const result = await client.callTool("list_kernels", {});

result = await session.call_tool("list_kernels", arguments={})

Response

{
  "result": "string"
}

list_kernels

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "list_kernels",
    "arguments": {}
  }
}

const result = await client.callTool("list_kernels", {});

result = await session.call_tool("list_kernels", arguments={})

Response

{
  "result": "string"
}

use_notebook

destructive

TOOLuse_notebook

Use a notebook and activate it for following cell operations. All cell operations will be performed on the currently activated notebook. Activate new notebook will deactivate the previously activated notebook. Reactivate previously activated notebook using same notebook_name and notebook_path.

Parameters

notebook_namestringrequiredargument

Unique identifier for the notebook

notebook_pathstringrequiredargument

Path to the notebook file, relative to the Jupyter server root (e.g. 'notebook.ipynb')

modestringconnectcreateconnectargument

Notebook operation mode: 'connect' to connect to existing and activate it, 'create' to create new and activate it

kernel_idstringnullargument

Specific kernel ID to use (will create new if skipped)

Returns

resultstringrequired

Success message with notebook information

use_notebook

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "use_notebook",
    "arguments": {
        "notebook_name": "string",
        "notebook_path": "string",
        "mode": "connect",
        "kernel_id": null
      }
  }
}

const result = await client.callTool("use_notebook", {
  "notebook_name": "string",
  "notebook_path": "string",
  "mode": "connect",
  "kernel_id": null
});

result = await session.call_tool("use_notebook", arguments={
  "notebook_name": "string",
  "notebook_path": "string",
  "mode": "connect",
  "kernel_id": null
})

Response

{
  "result": "string"
}

use_notebook

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "use_notebook",
    "arguments": {
        "notebook_name": "string",
        "notebook_path": "string",
        "mode": "connect",
        "kernel_id": null
      }
  }
}

const result = await client.callTool("use_notebook", {
  "notebook_name": "string",
  "notebook_path": "string",
  "mode": "connect",
  "kernel_id": null
});

result = await session.call_tool("use_notebook", arguments={
  "notebook_name": "string",
  "notebook_path": "string",
  "mode": "connect",
  "kernel_id": null
})

Response

{
  "result": "string"
}

list_notebooks

read-only

TOOLlist_notebooks

List all notebooks that have been used via use_notebook tool

Returns

resultstringrequired

TSV formatted table with notebook information

list_notebooks

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "list_notebooks",
    "arguments": {}
  }
}

const result = await client.callTool("list_notebooks", {});

result = await session.call_tool("list_notebooks", arguments={})

Response

{
  "result": "string"
}

list_notebooks

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "list_notebooks",
    "arguments": {}
  }
}

const result = await client.callTool("list_notebooks", {});

result = await session.call_tool("list_notebooks", arguments={})

Response

{
  "result": "string"
}

restart_notebook

destructive

TOOLrestart_notebook

Restart the kernel for a specific notebook.

Parameters

notebook_namestringrequiredargument

Notebook identifier to restart

Returns

resultstringrequired

Success message

restart_notebook

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "restart_notebook",
    "arguments": {
        "notebook_name": "string"
      }
  }
}

const result = await client.callTool("restart_notebook", {
  "notebook_name": "string"
});

result = await session.call_tool("restart_notebook", arguments={
  "notebook_name": "string"
})

Response

{
  "result": "string"
}

restart_notebook

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "restart_notebook",
    "arguments": {
        "notebook_name": "string"
      }
  }
}

const result = await client.callTool("restart_notebook", {
  "notebook_name": "string"
});

result = await session.call_tool("restart_notebook", arguments={
  "notebook_name": "string"
})

Response

{
  "result": "string"
}

unuse_notebook

destructive

TOOLunuse_notebook

Unuse from a specific notebook and release its resources.

Parameters

notebook_namestringrequiredargument

Notebook identifier to disconnect

Returns

resultstringrequired

Success message

unuse_notebook

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unuse_notebook",
    "arguments": {
        "notebook_name": "string"
      }
  }
}

const result = await client.callTool("unuse_notebook", {
  "notebook_name": "string"
});

result = await session.call_tool("unuse_notebook", arguments={
  "notebook_name": "string"
})

Response

{
  "result": "string"
}

unuse_notebook

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unuse_notebook",
    "arguments": {
        "notebook_name": "string"
      }
  }
}

const result = await client.callTool("unuse_notebook", {
  "notebook_name": "string"
});

result = await session.call_tool("unuse_notebook", arguments={
  "notebook_name": "string"
})

Response

{
  "result": "string"
}

read_notebook

read-only

TOOLread_notebook

Read a notebook and return index, source content, type, execution count of each cell.

Using brief format to get a quick overview of the notebook structure and it's useful for locating specific cells for operations like delete or insert. Using detailed format to get detailed information of the notebook and it's useful for debugging and analysis.

It is recommended to use brief format with larger limit to get a overview of the notebook structure, then use detailed format with exact index and limit to get the detailed information of some specific cells.

Parameters

notebook_namestringrequiredargument

Notebook identifier to read

response_formatstringbriefdetailedbriefargument

Response format: 'brief' will return first line and lines number, 'detailed' will return full cell source

start_indexinteger>= 00argument

Starting index for pagination (0-based)

limitinteger>= 020argument

Maximum number of items to return (0 means no limit)

Returns

resultstringrequired

Notebook content in the requested format

read_notebook

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "read_notebook",
    "arguments": {
        "notebook_name": "string",
        "response_format": "brief",
        "start_index": 0,
        "limit": 20
      }
  }
}

const result = await client.callTool("read_notebook", {
  "notebook_name": "string",
  "response_format": "brief",
  "start_index": 0,
  "limit": 20
});

result = await session.call_tool("read_notebook", arguments={
  "notebook_name": "string",
  "response_format": "brief",
  "start_index": 0,
  "limit": 20
})

Response

{
  "result": "string"
}

read_notebook

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "read_notebook",
    "arguments": {
        "notebook_name": "string",
        "response_format": "brief",
        "start_index": 0,
        "limit": 20
      }
  }
}

const result = await client.callTool("read_notebook", {
  "notebook_name": "string",
  "response_format": "brief",
  "start_index": 0,
  "limit": 20
});

result = await session.call_tool("read_notebook", arguments={
  "notebook_name": "string",
  "response_format": "brief",
  "start_index": 0,
  "limit": 20
})

Response

{
  "result": "string"
}

insert_cell

destructive

TOOLinsert_cell

Insert a cell to specified position from the currently activated notebook.

Body

application/json

cell_indexinteger>= -1required

Target index for insertion (0-based), use -1 to append at end

cell_typestringcodemarkdownrequired

Type of cell to insert

cell_sourcestringrequired

Source content for the cell

notebook_namestring | nullnull

Target this specific connected notebook instead of the currently activated one. Use when multiple clients share this server, to avoid racing the shared 'current notebook' pointer. Omit to use the currently activated notebook.

Returns

resultstringrequired

Success message and the structure of its surrounding cells

insert_cell

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "insert_cell",
    "arguments": {
        "cell_index": -1,
        "cell_type": "code",
        "cell_source": "string",
        "notebook_name": null
      }
  }
}

const result = await client.callTool("insert_cell", {
  "cell_index": -1,
  "cell_type": "code",
  "cell_source": "string",
  "notebook_name": null
});

result = await session.call_tool("insert_cell", arguments={
  "cell_index": -1,
  "cell_type": "code",
  "cell_source": "string",
  "notebook_name": null
})

Request Body

{
  "cell_index": -1,
  "cell_type": "code",
  "cell_source": "string",
  "notebook_name": null
}

Response

{
  "result": "string"
}

insert_cell

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "insert_cell",
    "arguments": {
        "cell_index": -1,
        "cell_type": "code",
        "cell_source": "string",
        "notebook_name": null
      }
  }
}

const result = await client.callTool("insert_cell", {
  "cell_index": -1,
  "cell_type": "code",
  "cell_source": "string",
  "notebook_name": null
});

result = await session.call_tool("insert_cell", arguments={
  "cell_index": -1,
  "cell_type": "code",
  "cell_source": "string",
  "notebook_name": null
})

Request Body

{
  "cell_index": -1,
  "cell_type": "code",
  "cell_source": "string",
  "notebook_name": null
}

Response

{
  "result": "string"
}

overwrite_cell_source

destructive

TOOLoverwrite_cell_source

Replace the entire source of a cell in the currently activated notebook. Returns a diff showing the changes made.

Use this when rewriting a cell completely. For small, targeted changes, prefer edit_cell_source instead — it is safer for partial edits.

Body

application/json

cell_indexinteger>= 0required

Index of the cell to overwrite (0-based)

cell_sourcestringrequired

New complete cell source

notebook_namestring | nullnull

Returns

resultstringrequired

Success message with diff showing changes made

overwrite_cell_source

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "overwrite_cell_source",
    "arguments": {
        "cell_index": 0,
        "cell_source": "string",
        "notebook_name": null
      }
  }
}

const result = await client.callTool("overwrite_cell_source", {
  "cell_index": 0,
  "cell_source": "string",
  "notebook_name": null
});

result = await session.call_tool("overwrite_cell_source", arguments={
  "cell_index": 0,
  "cell_source": "string",
  "notebook_name": null
})

Request Body

{
  "cell_index": 0,
  "cell_source": "string",
  "notebook_name": null
}

Response

{
  "result": "string"
}

overwrite_cell_source

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "overwrite_cell_source",
    "arguments": {
        "cell_index": 0,
        "cell_source": "string",
        "notebook_name": null
      }
  }
}

const result = await client.callTool("overwrite_cell_source", {
  "cell_index": 0,
  "cell_source": "string",
  "notebook_name": null
});

result = await session.call_tool("overwrite_cell_source", arguments={
  "cell_index": 0,
  "cell_source": "string",
  "notebook_name": null
})

Request Body

{
  "cell_index": 0,
  "cell_source": "string",
  "notebook_name": null
}

Response

{
  "result": "string"
}

edit_cell_source

destructive

TOOLedit_cell_source

Perform a surgical find-and-replace within a cell's source (like an editor's Edit tool). Finds old_string in the cell and replaces it with new_string. Matching is literal (not regex) and may span multiple lines. By default, old_string must appear exactly once; set replace_all=True for multiple occurrences. Returns a diff of the changes made.

Prefer this over overwrite_cell_source for small, targeted edits — it is safer because unchanged parts of the cell are left untouched. Use read_cell first to see the current source and construct an accurate old_string.

Body

application/json

cell_indexinteger>= 0required

Index of the cell to edit (0-based)

old_stringstringrequired

Exact string to find in cell source

new_stringstringrequired

Replacement string

replace_allbooleanfalse

Replace all occurrences (default: first only)

notebook_namestring | nullnull

Returns

resultstringrequired

Success message with diff showing changes made

edit_cell_source

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "edit_cell_source",
    "arguments": {
        "cell_index": 0,
        "old_string": "string",
        "new_string": "string",
        "replace_all": false,
        "notebook_name": null
      }
  }
}

const result = await client.callTool("edit_cell_source", {
  "cell_index": 0,
  "old_string": "string",
  "new_string": "string",
  "replace_all": false,
  "notebook_name": null
});

result = await session.call_tool("edit_cell_source", arguments={
  "cell_index": 0,
  "old_string": "string",
  "new_string": "string",
  "replace_all": false,
  "notebook_name": null
})

Request Body

{
  "cell_index": 0,
  "old_string": "string",
  "new_string": "string",
  "replace_all": false,
  "notebook_name": null
}

Response

{
  "result": "string"
}

edit_cell_source

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "edit_cell_source",
    "arguments": {
        "cell_index": 0,
        "old_string": "string",
        "new_string": "string",
        "replace_all": false,
        "notebook_name": null
      }
  }
}

const result = await client.callTool("edit_cell_source", {
  "cell_index": 0,
  "old_string": "string",
  "new_string": "string",
  "replace_all": false,
  "notebook_name": null
});

result = await session.call_tool("edit_cell_source", arguments={
  "cell_index": 0,
  "old_string": "string",
  "new_string": "string",
  "replace_all": false,
  "notebook_name": null
})

Request Body

{
  "cell_index": 0,
  "old_string": "string",
  "new_string": "string",
  "replace_all": false,
  "notebook_name": null
}

Response

{
  "result": "string"
}

execute_cell

destructive

TOOLexecute_cell

Execute a cell from the currently activated notebook with timeout and return it's outputs

Parameters

cell_indexinteger>= 0requiredargument

Index of the cell to execute (0-based)

timeoutinteger0argument

Maximum seconds to wait for execution (0 = use config default)

streambooleantrueargument

Enable streaming progress (including time indicator) updates for long-running cells

progress_intervalinteger5argument

Seconds between progress updates (MCP keepalive + optional stream log)

Returns

Returns MCP content array (text, image, or embedded resource).

execute_cell

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "execute_cell",
    "arguments": {
        "cell_index": 0,
        "timeout": 0,
        "stream": true,
        "progress_interval": 5
      }
  }
}

const result = await client.callTool("execute_cell", {
  "cell_index": 0,
  "timeout": 0,
  "stream": true,
  "progress_interval": 5
});

result = await session.call_tool("execute_cell", arguments={
  "cell_index": 0,
  "timeout": 0,
  "stream": true,
  "progress_interval": 5
})

Response

{
  "content": [
    {
      "type": "text",
      "text": "..."
    }
  ]
}

execute_cell

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "execute_cell",
    "arguments": {
        "cell_index": 0,
        "timeout": 0,
        "stream": true,
        "progress_interval": 5
      }
  }
}

const result = await client.callTool("execute_cell", {
  "cell_index": 0,
  "timeout": 0,
  "stream": true,
  "progress_interval": 5
});

result = await session.call_tool("execute_cell", arguments={
  "cell_index": 0,
  "timeout": 0,
  "stream": true,
  "progress_interval": 5
})

Response

{
  "content": [
    {
      "type": "text",
      "text": "..."
    }
  ]
}

insert_execute_code_cell

destructive

TOOLinsert_execute_code_cell

Insert a cell at specified index from the currently activated notebook and then execute it with timeout and return it's outputs It is a shortcut tool for insert_cell and execute_cell tools, recommended to use if you want to insert a cell and execute it at the same time

Parameters

cell_indexinteger>= -1requiredargument

Index of the cell to insert and execute (0-based)

cell_sourcestringrequiredargument

Code source for the cell

timeoutinteger0argument

Maximum seconds to wait for execution (0 = use config default)

streambooleantrueargument

Enable streaming progress (including time indicator) updates for long-running cells

progress_intervalinteger5argument

Seconds between progress updates (MCP keepalive + optional stream log)

Returns

Returns MCP content array (text, image, or embedded resource).

insert_execute_code_cell

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "insert_execute_code_cell",
    "arguments": {
        "cell_index": -1,
        "cell_source": "string",
        "timeout": 0,
        "stream": true,
        "progress_interval": 5
      }
  }
}

const result = await client.callTool("insert_execute_code_cell", {
  "cell_index": -1,
  "cell_source": "string",
  "timeout": 0,
  "stream": true,
  "progress_interval": 5
});

result = await session.call_tool("insert_execute_code_cell", arguments={
  "cell_index": -1,
  "cell_source": "string",
  "timeout": 0,
  "stream": true,
  "progress_interval": 5
})

Response

{
  "content": [
    {
      "type": "text",
      "text": "..."
    }
  ]
}

insert_execute_code_cell

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "insert_execute_code_cell",
    "arguments": {
        "cell_index": -1,
        "cell_source": "string",
        "timeout": 0,
        "stream": true,
        "progress_interval": 5
      }
  }
}

const result = await client.callTool("insert_execute_code_cell", {
  "cell_index": -1,
  "cell_source": "string",
  "timeout": 0,
  "stream": true,
  "progress_interval": 5
});

result = await session.call_tool("insert_execute_code_cell", arguments={
  "cell_index": -1,
  "cell_source": "string",
  "timeout": 0,
  "stream": true,
  "progress_interval": 5
})

Response

{
  "content": [
    {
      "type": "text",
      "text": "..."
    }
  ]
}

read_cell

read-only

TOOLread_cell

Read a specific cell from the currently activated notebook and return it's metadata (index, type, execution count), source and outputs (for code cells)

Body

application/json

cell_indexinteger>= 0required

Index of the cell to read (0-based)

include_outputsbooleantrue

Include outputs in the response (only for code cells)

notebook_namestring | nullnull

Returns

Returns MCP content array (text, image, or embedded resource).

read_cell

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "read_cell",
    "arguments": {
        "cell_index": 0,
        "include_outputs": true,
        "notebook_name": null
      }
  }
}

const result = await client.callTool("read_cell", {
  "cell_index": 0,
  "include_outputs": true,
  "notebook_name": null
});

result = await session.call_tool("read_cell", arguments={
  "cell_index": 0,
  "include_outputs": true,
  "notebook_name": null
})

Request Body

{
  "cell_index": 0,
  "include_outputs": true,
  "notebook_name": null
}

Response

{
  "content": [
    {
      "type": "text",
      "text": "..."
    }
  ]
}

read_cell

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "read_cell",
    "arguments": {
        "cell_index": 0,
        "include_outputs": true,
        "notebook_name": null
      }
  }
}

const result = await client.callTool("read_cell", {
  "cell_index": 0,
  "include_outputs": true,
  "notebook_name": null
});

result = await session.call_tool("read_cell", arguments={
  "cell_index": 0,
  "include_outputs": true,
  "notebook_name": null
})

Request Body

{
  "cell_index": 0,
  "include_outputs": true,
  "notebook_name": null
}

Response

{
  "content": [
    {
      "type": "text",
      "text": "..."
    }
  ]
}

delete_cell

destructive

TOOLdelete_cell

Delete specific cells from the currently activated notebook and return the cell source of deleted cells (if include_source=True).

Body

application/json

cell_indicesArray<integer>required

List of cell indices to delete (0-based)

include_sourcebooleantrue

Whether to include the source of deleted cells

notebook_namestring | nullnull

Returns

resultstringrequired

Success message with list of deleted cells and their source (if include_source=True)

delete_cell

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "delete_cell",
    "arguments": {
        "cell_indices": [
          0
        ],
        "include_source": true,
        "notebook_name": null
      }
  }
}

const result = await client.callTool("delete_cell", {
  "cell_indices": [
    0
  ],
  "include_source": true,
  "notebook_name": null
});

result = await session.call_tool("delete_cell", arguments={
  "cell_indices": [
    0
  ],
  "include_source": true,
  "notebook_name": null
})

Request Body

{
  "cell_indices": [
    0
  ],
  "include_source": true,
  "notebook_name": null
}

Response

{
  "result": "string"
}

delete_cell

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "delete_cell",
    "arguments": {
        "cell_indices": [
          0
        ],
        "include_source": true,
        "notebook_name": null
      }
  }
}

const result = await client.callTool("delete_cell", {
  "cell_indices": [
    0
  ],
  "include_source": true,
  "notebook_name": null
});

result = await session.call_tool("delete_cell", arguments={
  "cell_indices": [
    0
  ],
  "include_source": true,
  "notebook_name": null
})

Request Body

{
  "cell_indices": [
    0
  ],
  "include_source": true,
  "notebook_name": null
}

Response

{
  "result": "string"
}

clear_cell_output

destructive

TOOLclear_cell_output

Clear the outputs and execution count of a single code cell in the currently activated notebook, without deleting the cell itself.

Body

application/json

cell_indexinteger>= 0required

Index of the code cell to clear (0-based)

notebook_namestring | nullnull

Returns

resultstringrequired

Success message with the number of outputs removed

clear_cell_output

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "clear_cell_output",
    "arguments": {
        "cell_index": 0,
        "notebook_name": null
      }
  }
}

const result = await client.callTool("clear_cell_output", {
  "cell_index": 0,
  "notebook_name": null
});

result = await session.call_tool("clear_cell_output", arguments={
  "cell_index": 0,
  "notebook_name": null
})

Request Body

{
  "cell_index": 0,
  "notebook_name": null
}

Response

{
  "result": "string"
}

clear_cell_output

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "clear_cell_output",
    "arguments": {
        "cell_index": 0,
        "notebook_name": null
      }
  }
}

const result = await client.callTool("clear_cell_output", {
  "cell_index": 0,
  "notebook_name": null
});

result = await session.call_tool("clear_cell_output", arguments={
  "cell_index": 0,
  "notebook_name": null
})

Request Body

{
  "cell_index": 0,
  "notebook_name": null
}

Response

{
  "result": "string"
}

move_cell

destructive

TOOLmove_cell

Move a cell from source_index to target_index within the currently activated notebook.

The cell is removed from source_index and placed at target_index. Cells in between shift to fill the gap. The cell's type, source, and outputs are preserved. Example: in a notebook [A, B, C, D], move_cell(1, 3) produces [A, C, D, B].

Use this tool instead of manually deleting and re-inserting a cell — it is atomic and preserves cell metadata. Use read_notebook first to see cell indices if needed.

Body

application/json

source_indexinteger>= 0required

Index of the cell to move (0-based)

target_indexinteger>= 0required

Destination index where the cell will end up (0-based)

notebook_namestring | nullnull

Returns

resultstringrequired

Success message with moved cell info and surrounding context

move_cell

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "move_cell",
    "arguments": {
        "source_index": 0,
        "target_index": 0,
        "notebook_name": null
      }
  }
}

const result = await client.callTool("move_cell", {
  "source_index": 0,
  "target_index": 0,
  "notebook_name": null
});

result = await session.call_tool("move_cell", arguments={
  "source_index": 0,
  "target_index": 0,
  "notebook_name": null
})

Request Body

{
  "source_index": 0,
  "target_index": 0,
  "notebook_name": null
}

Response

{
  "result": "string"
}

move_cell

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "move_cell",
    "arguments": {
        "source_index": 0,
        "target_index": 0,
        "notebook_name": null
      }
  }
}

const result = await client.callTool("move_cell", {
  "source_index": 0,
  "target_index": 0,
  "notebook_name": null
});

result = await session.call_tool("move_cell", arguments={
  "source_index": 0,
  "target_index": 0,
  "notebook_name": null
})

Request Body

{
  "source_index": 0,
  "target_index": 0,
  "notebook_name": null
}

Response

{
  "result": "string"
}

execute_code

destructive

TOOLexecute_code

Execute code directly in a kernel (not saved to notebook).

If use_sandbox selected an active sandbox, this tool executes on that sandbox instead of a Jupyter kernel. This allows agents to switch between kernel-backed and sandbox-backed execution using the same execute_code API.

Targets the current activated notebook's kernel by default. Pass kernel_id to execute in a specific kernel directly — including raw kernels with no notebook attached.

Recommended to use in following cases:

Execute Jupyter magic commands(e.g., %timeit, %pip install xxx)
Performance profiling and debugging.
View intermediate variable values(e.g., print(xxx), df.head())
Temporary calculations and quick tests(e.g., np.mean(df['xxx']))
Execute Shell commands in Jupyter server(e.g., !git xxx)

Under no circumstances should you use this tool to:

Import new modules or perform variable assignments that affect subsequent Notebook execution
Execute dangerous code that may harm the Jupyter server or the user's data without permission

Body

application/json

codestringrequired

Code to execute (supports magic commands with %, shell commands with !)

timeoutinteger30

Maximum seconds to wait for execution (0 = use config default)

kernel_idstring | nullnull

Target an existing kernel by ID (e.g. a raw kernel with no notebook). If omitted, uses the current notebook's kernel.

progress_intervalinteger5

Seconds between MCP progress keepalive updates during long-running execution

Returns

Returns MCP content array (text, image, or embedded resource).

execute_code

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "execute_code",
    "arguments": {
        "code": "string",
        "timeout": 30,
        "kernel_id": null,
        "progress_interval": 5
      }
  }
}

const result = await client.callTool("execute_code", {
  "code": "string",
  "timeout": 30,
  "kernel_id": null,
  "progress_interval": 5
});

result = await session.call_tool("execute_code", arguments={
  "code": "string",
  "timeout": 30,
  "kernel_id": null,
  "progress_interval": 5
})

Request Body

{
  "code": "string",
  "timeout": 30,
  "kernel_id": null,
  "progress_interval": 5
}

Response

{
  "content": [
    {
      "type": "text",
      "text": "..."
    }
  ]
}

execute_code

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "execute_code",
    "arguments": {
        "code": "string",
        "timeout": 30,
        "kernel_id": null,
        "progress_interval": 5
      }
  }
}

const result = await client.callTool("execute_code", {
  "code": "string",
  "timeout": 30,
  "kernel_id": null,
  "progress_interval": 5
});

result = await session.call_tool("execute_code", arguments={
  "code": "string",
  "timeout": 30,
  "kernel_id": null,
  "progress_interval": 5
})

Request Body

{
  "code": "string",
  "timeout": 30,
  "kernel_id": null,
  "progress_interval": 5
}

Response

{
  "content": [
    {
      "type": "text",
      "text": "..."
    }
  ]
}

connect_to_jupyter

destructive

TOOLconnect_to_jupyter

Connect to a Jupyter server dynamically with URL and token.

This tool allows you to connect to different Jupyter servers without needing to restart the MCP server or modify configuration files. Particularly useful when:

Working with multiple Jupyter servers with different ports/tokens
Jupyter server token changes dynamically
Need to switch between different Jupyter instances

Example usage:

"Connect to http://localhost:8888 with token abc123"
"Connect to http://localhost:8889 without authentication"

Body

application/json

jupyter_urlstringrequired

Jupyter server URL to connect to (e.g., 'http://localhost:8888')

jupyter_tokenstring | nullnull

Jupyter server authentication token

providerstringjupyter

Provider type

Returns

resultstringrequired

Connection status message

connect_to_jupyter

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "connect_to_jupyter",
    "arguments": {
        "jupyter_url": "string",
        "jupyter_token": null,
        "provider": "jupyter"
      }
  }
}

const result = await client.callTool("connect_to_jupyter", {
  "jupyter_url": "string",
  "jupyter_token": null,
  "provider": "jupyter"
});

result = await session.call_tool("connect_to_jupyter", arguments={
  "jupyter_url": "string",
  "jupyter_token": null,
  "provider": "jupyter"
})

Request Body

{
  "jupyter_url": "string",
  "jupyter_token": null,
  "provider": "jupyter"
}

Response

{
  "result": "string"
}

connect_to_jupyter

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "connect_to_jupyter",
    "arguments": {
        "jupyter_url": "string",
        "jupyter_token": null,
        "provider": "jupyter"
      }
  }
}

const result = await client.callTool("connect_to_jupyter", {
  "jupyter_url": "string",
  "jupyter_token": null,
  "provider": "jupyter"
});

result = await session.call_tool("connect_to_jupyter", arguments={
  "jupyter_url": "string",
  "jupyter_token": null,
  "provider": "jupyter"
})

Request Body

{
  "jupyter_url": "string",
  "jupyter_token": null,
  "provider": "jupyter"
}

Response

{
  "result": "string"
}

launch_sandbox

destructive

TOOLlaunch_sandbox

Launch a code sandbox that can be used instead of Jupyter kernels.

After launch, call use_sandbox to make execute_code run on this sandbox (as an alternative to notebook-bound kernel execution). Works in both MCP_SERVER and JUPYTER_SERVER modes.

Body

application/json

sandbox_namestringrequired

Unique sandbox identifier used by list/use/terminate tools

variantstring | nullnull

Sandbox variant to launch. If omitted, defaults to configured SANDBOX_VARIANT when it is non-jupyter; otherwise falls back to eval.

timeoutinteger>= 160

Default execution timeout in seconds for this sandbox

environmentstring | nullnull

Optional sandbox environment name (common for datalayer/modal variants)

gpustring | nullnull

Optional GPU flavor / accelerator for supported variants (modal/datalayer examples: T4, A10G, A100, H100; kaggle examples: NvidiaTeslaT4, NvidiaTeslaP100, or aliases T4/P100).

server_urlstring | nullnull

Code Sandbox proxy URL when using colab or kaggle variant

kernel_idstring | nullnull

Kernel ID when using colab or kaggle variant

proxy_tokenstring | nullnull

Colab code sandbox proxy token when using colab variant

channels_urlstring | nullnull

Notebook session WebSocket channels URL to derive server_url/kernel_id (colab or kaggle variant)

tokenstring | nullnull

Datalayer API token override, or Kaggle API token for the kaggle variant (falls back to KAGGLE_API_TOKEN)

run_urlstring | nullnull

Datalayer run URL override

python_versionstring | nullnull

Modal Python version override (e.g. 3.12). Only used for modal variant.

Returns

Returns MCP content array (text, image, or embedded resource).

launch_sandbox

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "launch_sandbox",
    "arguments": {
        "sandbox_name": "string",
        "variant": null,
        "timeout": 60,
        "environment": null,
        "gpu": null,
        "server_url": null,
        "kernel_id": null,
        "proxy_token": null,
        "channels_url": null,
        "token": null,
        "run_url": null,
        "python_version": null
      }
  }
}

const result = await client.callTool("launch_sandbox", {
  "sandbox_name": "string",
  "variant": null,
  "timeout": 60,
  "environment": null,
  "gpu": null,
  "server_url": null,
  "kernel_id": null,
  "proxy_token": null,
  "channels_url": null,
  "token": null,
  "run_url": null,
  "python_version": null
});

result = await session.call_tool("launch_sandbox", arguments={
  "sandbox_name": "string",
  "variant": null,
  "timeout": 60,
  "environment": null,
  "gpu": null,
  "server_url": null,
  "kernel_id": null,
  "proxy_token": null,
  "channels_url": null,
  "token": null,
  "run_url": null,
  "python_version": null
})

Request Body

{
  "sandbox_name": "string",
  "variant": null,
  "timeout": 60,
  "environment": null,
  "gpu": null,
  "server_url": null,
  "kernel_id": null,
  "proxy_token": null,
  "channels_url": null,
  "token": null,
  "run_url": null,
  "python_version": null
}

Response

{
  "content": [
    {
      "type": "text",
      "text": "..."
    }
  ]
}

launch_sandbox

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "launch_sandbox",
    "arguments": {
        "sandbox_name": "string",
        "variant": null,
        "timeout": 60,
        "environment": null,
        "gpu": null,
        "server_url": null,
        "kernel_id": null,
        "proxy_token": null,
        "channels_url": null,
        "token": null,
        "run_url": null,
        "python_version": null
      }
  }
}

const result = await client.callTool("launch_sandbox", {
  "sandbox_name": "string",
  "variant": null,
  "timeout": 60,
  "environment": null,
  "gpu": null,
  "server_url": null,
  "kernel_id": null,
  "proxy_token": null,
  "channels_url": null,
  "token": null,
  "run_url": null,
  "python_version": null
});

result = await session.call_tool("launch_sandbox", arguments={
  "sandbox_name": "string",
  "variant": null,
  "timeout": 60,
  "environment": null,
  "gpu": null,
  "server_url": null,
  "kernel_id": null,
  "proxy_token": null,
  "channels_url": null,
  "token": null,
  "run_url": null,
  "python_version": null
})

Request Body

{
  "sandbox_name": "string",
  "variant": null,
  "timeout": 60,
  "environment": null,
  "gpu": null,
  "server_url": null,
  "kernel_id": null,
  "proxy_token": null,
  "channels_url": null,
  "token": null,
  "run_url": null,
  "python_version": null
}

Response

{
  "content": [
    {
      "type": "text",
      "text": "..."
    }
  ]
}

list_sandboxes

read-only

TOOLlist_sandboxes

List launched code sandboxes that can be used as alternatives to kernels.

Returns

resultArray<object>required

All launched sandboxes with name, variant, status, and active flag

list_sandboxes

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "list_sandboxes",
    "arguments": {}
  }
}

const result = await client.callTool("list_sandboxes", {});

result = await session.call_tool("list_sandboxes", arguments={})

Response

{
  "result": [
    {}
  ]
}

list_sandboxes

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "list_sandboxes",
    "arguments": {}
  }
}

const result = await client.callTool("list_sandboxes", {});

result = await session.call_tool("list_sandboxes", arguments={})

Response

{
  "result": [
    {}
  ]
}

use_sandbox

destructive

TOOLuse_sandbox

Select which launched sandbox execute_code should use instead of kernels.

Body

application/json

sandbox_namestring | nullnull

Sandbox name to activate for execute_code. Pass null/empty to disable sandbox routing and return to Jupyter kernels.

Returns

resultstringrequired

Sandbox routing status

use_sandbox

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "use_sandbox",
    "arguments": {
        "sandbox_name": null
      }
  }
}

const result = await client.callTool("use_sandbox", {
  "sandbox_name": null
});

result = await session.call_tool("use_sandbox", arguments={
  "sandbox_name": null
})

Request Body

{
  "sandbox_name": null
}

Response

{
  "result": "string"
}

use_sandbox

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "use_sandbox",
    "arguments": {
        "sandbox_name": null
      }
  }
}

const result = await client.callTool("use_sandbox", {
  "sandbox_name": null
});

result = await session.call_tool("use_sandbox", arguments={
  "sandbox_name": null
})

Request Body

{
  "sandbox_name": null
}

Response

{
  "result": "string"
}

terminate_sandbox

destructive

TOOLterminate_sandbox

Terminate a launched code sandbox.

Parameters

sandbox_namestringrequiredargument

Sandbox name to terminate and unregister

Returns

resultstringrequired

Termination status message

terminate_sandbox

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "terminate_sandbox",
    "arguments": {
        "sandbox_name": "string"
      }
  }
}

const result = await client.callTool("terminate_sandbox", {
  "sandbox_name": "string"
});

result = await session.call_tool("terminate_sandbox", arguments={
  "sandbox_name": "string"
})

Response

{
  "result": "string"
}

terminate_sandbox

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "terminate_sandbox",
    "arguments": {
        "sandbox_name": "string"
      }
  }
}

const result = await client.callTool("terminate_sandbox", {
  "sandbox_name": "string"
});

result = await session.call_tool("terminate_sandbox", arguments={
  "sandbox_name": "string"
})

Response

{
  "result": "string"
}

Prompts

jupyter_cite

PROMPTjupyter_cite

Like @ or # in Coding IDE or CLI, cite specific cells from specified notebook and insert them into the prompt.

Parameters

promptstringrequiredargument

User prompt for the cited cells

cell_indicesstringrequiredargument

Cell indices to cite (0-based),supporting flexible range format, e.g., '0,1,2', '0-2' or '0-2,4'

notebook_namestringargument

Name of the notebook to cite cells from, default (empty) to current activated notebook

Returns

Returns MCP content array (text, image, or embedded resource).

jupyter_cite

{
  "jsonrpc": "2.0",
  "method": "prompts/get",
  "params": {
    "name": "jupyter_cite",
    "arguments": {
        "prompt": "<prompt>",
        "cell_indices": "<cell_indices>",
        "notebook_name": "<notebook_name>"
      }
  }
}

const result = await client.getPrompt("jupyter_cite", {
  prompt: "<prompt>",
  cell_indices: "<cell_indices>",
  notebook_name: "<notebook_name>",
});

result = await session.get_prompt("jupyter_cite", arguments={
    "prompt": "<prompt>",
    "cell_indices": "<cell_indices>",
    "notebook_name": "<notebook_name>",
})

Response

{
  "content": [
    {
      "type": "text",
      "text": "..."
    }
  ]
}

jupyter_cite

{
  "jsonrpc": "2.0",
  "method": "prompts/get",
  "params": {
    "name": "jupyter_cite",
    "arguments": {
        "prompt": "<prompt>",
        "cell_indices": "<cell_indices>",
        "notebook_name": "<notebook_name>"
      }
  }
}

const result = await client.getPrompt("jupyter_cite", {
  prompt: "<prompt>",
  cell_indices: "<cell_indices>",
  notebook_name: "<notebook_name>",
});

result = await session.get_prompt("jupyter_cite", arguments={
    "prompt": "<prompt>",
    "cell_indices": "<cell_indices>",
    "notebook_name": "<notebook_name>",
})

Response

{
  "content": [
    {
      "type": "text",
      "text": "..."
    }
  ]
}