MCP Jupyter Server

Instructions

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"]
    }
  },