execute_cell
Execute a specific cell in a Jupyter notebook to run code and generate output using the notebook's kernel.
Instructions
Execute a specific cell in the notebook using a Jupyter kernel
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| notebook_path | Yes | Absolute path to the Jupyter notebook file | |
| cell_id | Yes | Cell ID or zero-based index of the cell to execute |
Implementation Reference
- src/jupyter-handler.js:447-589 (handler)The core handler function that executes the specified cell in the Jupyter notebook. It locates the cell by ID or index, uses a kernel session to execute the code, captures outputs, updates the notebook file with execution results, and returns formatted output or error.async executeCell(notebookPath, cellId) { try { const notebook = await this.readNotebook(notebookPath); // Find cell by ID or index let cellIndex = -1; let cell = null; if (typeof cellId === 'string') { // Search by cell ID cellIndex = notebook.cells.findIndex(c => c.id === cellId); if (cellIndex === -1) { throw new Error(`Cell with ID '${cellId}' not found`); } } else { // Treat as index cellIndex = cellId; this.validateCellIndex(notebook.cells, cellIndex); } cell = notebook.cells[cellIndex]; if (cell.cell_type !== 'code') { throw new Error(`Cell ${cellId} is not a code cell (type: ${cell.cell_type})`); } // Get kernel session const session = await this.getKernelSession(notebookPath); const kernel = session.kernel; if (!kernel) { throw new Error('No kernel available for execution'); } // Get cell source const source = Array.isArray(cell.source) ? cell.source.join('') : cell.source; if (!source.trim()) { return { content: [ { type: "text", text: "Cell is empty, nothing to execute" } ] }; } // Execute the code const future = kernel.requestExecute({ code: source }); const outputs = []; let executionCount = null; // Collect outputs future.onIOPub = (msg) => { if (msg.header.msg_type === 'execute_result' || msg.header.msg_type === 'display_data' || msg.header.msg_type === 'stream' || msg.header.msg_type === 'error') { outputs.push(msg.content); } if (msg.header.msg_type === 'execute_input') { executionCount = msg.content.execution_count; } }; // Wait for execution to complete const reply = await future.done; // Update cell in notebook cell.execution_count = executionCount; cell.outputs = outputs.map(output => { // Convert Jupyter message format to notebook format if (output.output_type) { return output; } else { // Handle different message types const notebookOutput = { output_type: reply.content.status === 'error' ? 'error' : 'execute_result' }; if (output.data) { notebookOutput.data = output.data; notebookOutput.metadata = output.metadata || {}; notebookOutput.execution_count = executionCount; } else if (output.text) { notebookOutput.output_type = 'stream'; notebookOutput.name = 'stdout'; notebookOutput.text = output.text; } return notebookOutput; } }); // Save updated notebook await this.writeNotebook(notebookPath, notebook); // Format output for display let outputText = `Executed cell ${cellId}\n`; if (reply.content.status === 'error') { outputText += `Error: ${reply.content.ename}: ${reply.content.evalue}`; } else { outputText += `Execution completed successfully`; if (outputs.length > 0) { outputText += '\n\nOutputs:'; outputs.forEach((output, i) => { if (output.text) { outputText += `\n${Array.isArray(output.text) ? output.text.join('') : output.text}`; } else if (output.data && output.data['text/plain']) { const text = Array.isArray(output.data['text/plain']) ? output.data['text/plain'].join('') : output.data['text/plain']; outputText += `\n${text}`; } }); } } return { content: [ { type: "text", text: outputText } ] }; } catch (error) { return { content: [ { type: "text", text: `Error executing cell: ${error.message}` } ], isError: true }; } }
- src/index.js:241-254 (schema)Input schema definition for the 'execute_cell' tool, specifying parameters notebook_path (string) and cell_id (string or integer).inputSchema: { type: "object", properties: { notebook_path: { type: "string", description: "Absolute path to the Jupyter notebook file" }, cell_id: { type: ["string", "integer"], description: "Cell ID or zero-based index of the cell to execute" } }, required: ["notebook_path", "cell_id"] }
- src/index.js:378-379 (registration)Registration of the tool handler in the CallToolRequest switch statement, delegating execution to JupyterHandler's executeCell method.case "execute_cell": return await this.jupyterHandler.executeCell(args.notebook_path, args.cell_id);
- src/index.js:238-255 (registration)Tool registration in the ListTools response, including name, description, and input schema.{ name: "execute_cell", description: "Execute a specific cell in the notebook using a Jupyter kernel", inputSchema: { type: "object", properties: { notebook_path: { type: "string", description: "Absolute path to the Jupyter notebook file" }, cell_id: { type: ["string", "integer"], description: "Cell ID or zero-based index of the cell to execute" } }, required: ["notebook_path", "cell_id"] } },