Execute Python Code Securely in Docker
Unified, stateful local execution environment for Python, shell commands, and MCP tool calls made via a generated typed API.
Why it matters
Safely run Python code for AI agents using a secure, stateful sandbox environment. Integrate seamlessly with AI agents via an MCP server interface for data analysis and code operations.
Outcomes
What it gets done
Execute Python code within isolated Docker containers.
Manage Python package installations during build or execution.
Stream real-time output and return visualization plots.
Integrate with AI agents through a provided MCP server.
Install
Add it to your toolbox
Run in your project directory:
curl -fsSL https://spark.entire.vc/get/vb-ipybox | bash Capabilities
Tools your agent gets
Execute Python code in a secure Docker container with IPython kernel and streaming output.
Install Python packages during code execution or container build.
Retrieve plots and visualizations created during code execution.
Overview
ipybox MCP Server
ipybox is a local, stateful execution environment combining Python, shell commands, and MCP tool calls made via a generated typed Python API, with optional sandboxing and per-call approval. Use it for agents that need to call MCP tools programmatically alongside code and shell commands with local data access; this is a rewritten next-generation version, so pin <0.7 for the older API.
What it does
ipybox is a unified execution environment that runs Python code, shell commands, and programmatic MCP tool calls together in a stateful IPython kernel, with state persisting across executions. A single code block can mix Python, !cmd-style shell commands (with output captured into Python variables), and MCP tool calls - the latter invoked through a generated typed Python API rather than raw JSON ("code mode"), built via the companion project mcpygen, which turns MCP tool schemas into typed functions and Pydantic models.
It runs entirely locally, with no cloud dependency, and supports optional kernel sandboxing via Anthropic's sandbox-runtime to enforce OS-level filesystem and network restrictions. Application-level approval lets you gate individual tool calls or shell commands during code execution rather than approving an entire script at once.
When to use - and when NOT to
Use ipybox when you want an agent to write and execute code that calls MCP tools programmatically (as typed function calls) alongside regular Python and shell commands, in a persistent kernel session with fine-grained approval control and access to local data.
Do not use it if you need cloud-hosted, non-local execution - ipybox is designed to run on your own machine to give protected access to local data and tools. Note this is a complete rewrite ("next generation"); if you depend on the older API, pin pip install ipybox<0.7 to stay on the 0.6.x branch.
Inputs and outputs
Inputs are code blocks combining Python, shell commands (!cmd), and calls to the generated MCP tool API. Outputs are the code block's execution results (variables, printed output, captured shell output), persisted in kernel state for subsequent executions.
Capabilities
- Stateful execution: state persists across executions in the IPython kernel
- Unified execution: mix Python code, shell commands, and MCP tool calls in one code block
- Shell command execution via
!cmdsyntax with output capture into Python variables - Programmatic MCP tool calls through a generated typed Python API (via mcpygen) instead of raw JSON
- Application-level approval of individual tool calls and shell commands during execution
- Optional lightweight sandboxing via Anthropic's sandbox-runtime for filesystem/network restriction
- Fully local execution with no cloud dependencies
How to install
pip install ipybox
For the legacy API: pip install "ipybox<0.7". It's usable as a Python SDK for building applications, as an MCP server for code actions and programmatic tool calling, or via a Claude Code plugin that bundles the MCP server and a code-action skill.
Who it's for
Agent developers who want their agents to write and run code that calls MCP tools programmatically, with stateful execution, local data access, and per-call approval control.
Source README
ipybox
mcp-name: io.github.gradion-ai/ipybox
ipybox is a unified execution environment for Python code, shell commands, and programmatic MCP tool calls.
Overview
ipybox executes code blocks in a stateful IPython kernel. A code block can contain any combination of Python code, shell commands, and programmatic MCP tool calls. Kernels can be sandboxed with sandbox-runtime, enforcing filesystem and network restrictions at OS level.
It generates Python APIs for MCP server tools via mcpygen, and supports application-level approval of individual tool calls and shell commands during code execution. ipybox runs locally on your computer, enabling protected access to your local data and tools.
Documentation:
- 📚 Documentation
- 🏗️ Architecture
- 🤖 llms.txt
- 🤖 llms-full.txt
Capabilities
| Capability | Description |
|---|---|
| Stateful execution | State persists across executions in IPython kernels |
| Unified execution | Combine Python code, shell commands, and programmatic MCP tool calls in a code block |
| Shell command execution | Run shell commands via !cmd syntax, capture output into Python variables |
| Programmatic MCP tool calls | MCP tools called via generated Python API ("code mode"), not JSON directly |
| Python tool API generation | Typed functions and Pydantic models generated from MCP tool schemas via mcpygen |
| Application-level approval | Individual approval of tool calls and shell commands during code execution |
| Lightweight sandboxing | Optional kernel isolation via Anthropic's sandbox-runtime |
| Local execution | No cloud dependencies, everything runs locally on your machine |
Usage
| Component | Description |
|---|---|
| Python SDK | Python API for building applications on ipybox |
| MCP server | ipybox as MCP server for code actions and programmatic tool calling |
| Claude Code plugin | Plugin that bundles the ipybox MCP server and a code action skill |
FAQ
Common questions
Discussion
Questions & comments · 0
Sign In Sign in to leave a comment.