execute_ipython_cell
Run Python code in a stateful IPython kernel within a Docker container. Maintain variables, imports, and definitions across executions for iterative workflows. Supports async code with 'await' and sequential executions with shared kernel state.
Instructions
Execute Python code in a stateful IPython kernel within a Docker container.
The kernel maintains state across executions - variables, imports, and definitions
persist between calls. Each execution builds on the previous one, allowing you to
build complex workflows step by step. Use '!pip install package_name' to install
packages as needed.
The kernel has an active asyncio event loop, so use 'await' directly for async
code. DO NOT use asyncio.run() or create new event loops.
Executions are sequential (not concurrent) as they share kernel state. Use the
reset() tool to clear the kernel state and start fresh.
Returns:
str: Output text from execution, or empty string if no output.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | Python code to execute in the IPython kernel | |
| timeout | No | Maximum execution time in seconds before the kernel is interrupted |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- ipybox/mcp/server.py:103-142 (handler)The main asynchronous handler function for the 'execute_ipython_cell' tool. It executes the provided Python code in a stateful IPython kernel using ExecutionClient, handles timeouts, and raises appropriate errors. Includes input schema via Annotated Fields.
async def execute_ipython_cell( self, code: Annotated[ str, Field(description="Python code to execute in the IPython kernel"), ], timeout: Annotated[ float, Field(description="Maximum execution time in seconds before the kernel is interrupted") ] = 120, ) -> str: """Execute Python code in a stateful IPython kernel within a Docker container. The kernel maintains state across executions - variables, imports, and definitions persist between calls. Each execution builds on the previous one, allowing you to build complex workflows step by step. Use '!pip install package_name' to install packages as needed. The kernel has an active asyncio event loop, so use 'await' directly for async code. DO NOT use asyncio.run() or create new event loops. Executions are sequential (not concurrent) as they share kernel state. Use the reset() tool to clear the kernel state and start fresh. Returns: str: Output text from execution, or empty string if no output. """ await self.setup_task assert self.execution_client is not None try: async with self.executor_lock: result = await self.execution_client.execute(code, timeout=timeout) return result.text or "" except Exception as e: match e: case ExecutionError(): raise ExecutionError(e.args[0] + "\n" + e.trace) case _: raise e - ipybox/mcp/server.py:52-52 (registration)Registration of the 'execute_ipython_cell' method as an MCP tool using FastMCP's @tool decorator.
self.mcp.tool()(self.execute_ipython_cell)