<p align="left"> <img src="docs/images/ipybox-crop-nobg.png" alt="ipybox" width="300"> </p>

ipybox

mcp-name: io.github.gradion-ai/ipybox

<p align="left"> <a href="https://gradion-ai.github.io/ipybox/"><img alt="Website" src="https://img.shields.io/website?url=https%3A%2F%2Fgradion-ai.github.io%2Fipybox%2F&up_message=online&down_message=offline&label=docs"></a> <a href="https://pypi.org/project/ipybox/"><img alt="PyPI - Version" src="https://img.shields.io/pypi/v/ipybox?color=blue"></a> <a href="https://github.com/gradion-ai/ipybox/releases"><img alt="GitHub Release" src="https://img.shields.io/github/v/release/gradion-ai/ipybox"></a> <a href="https://github.com/gradion-ai/ipybox/actions"><img alt="GitHub Actions Workflow Status" src="https://img.shields.io/github/actions/workflow/status/gradion-ai/ipybox/test.yml"></a> <a href="https://github.com/gradion-ai/ipybox/blob/main/LICENSE"><img alt="GitHub License" src="https://img.shields.io/github/license/gradion-ai/ipybox?color=blueviolet"></a> </p>

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.

[!NOTE]
Next generation ipybox

This is the next generation of ipybox, a complete rewrite. Older versions are maintained on the 0.6.x branch and can be obtained with pip install ipybox<0.7.

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

[!TIP]
Freeact agent

Freeact is a general-purpose agent built on ipybox.