CodeBox-AI
About
A secure Python code execution service designed to integrate with LLMs like GPT and Claude, providing a self-hosted alternative to OpenAI's Code Interpreter. Now with MCP server.
Details
- License
- MIT
Explore
- Session-based Python code execution in Docker containers
- IPython kernel for rich output support
- Dynamic package installation with security controls
- Package allowlist/blocklist system
- Version control for security vulnerabilities
- Support for pip and conda installations
- State persistence between executions
- Support for plotting and visualization
- Code security validation
- AST-based code analysis
- Protection against dangerous imports and operations
- Support for Jupyter magic commands and shell operations
- Host directory mounting
- Mount local directories into the container
- Read-only or read-write access control
- Security validations to prevent access to sensitive paths
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
CodeBox-AICommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
- Python 3.9+
- Docker
- uv - Fast Python package installer and resolver
You can run the MCP server in several ways:
- Standalone (for MCP clients or Claude Desktop):
uv run mcp dev mcp_server.py
This starts the MCP server in development mode for local testing and debugging.
- Register with Claude Desktop:
uv run mcp install mcp_server.py --name "CodeBox-AI"
This will make your server available to Claude Desktop as a custom tool.
- Combined FastAPI + MCP server:
uv run run.py
This starts both the FastAPI API and the MCP server (MCP available at
/mcp).
- MCP server only:
uv run run.py --mode mcp
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync
3. Start the server:
uv run -m codeboxai.main
The API will be available at http://localhost:8000
For development, install with the development extras:
uv sync --extra "dev docs"
1. Create a new session:
curl -X POST http://localhost:8000/sessions \
-H "Content-Type: application/json" \
-d '{
"dependencies": ["numpy", "pandas"]
}'
2. Execute code in the session:
curl -X POST http://localhost:8000/execute \
-H "Content-Type: application/json" \
-d '{
"code": "x = 42\nprint(f\"Value of x: {x}\")",
"session_id": "YOUR_SESSION_ID"
}'
3. Check execution status:
curl -X GET http://localhost:8000/execute/YOUR_REQUEST_ID/status
4. Get execution results:
curl -X GET http://localhost:8000/execute/YOUR_REQUEST_ID/results
5. Execute more code in the same session:
curl -X POST http://localhost:8000/execute \
-H "Content-Type: application/json" \
-d '{
"code": "print(f\"x is still: {x}\")",
"session_id": "YOUR_SESSION_ID"
}'
6. Create a session with mounted directories:
curl -X POST http://localhost:8000/sessions \
-H "Content-Type: application/json" \
-d '{
"execution_options": {
"mount_points": [
{
"host_path": "/Users/tconte/Downloads",
"container_path": "/data/downloads",
"read_only": true
}
],
"timeout": 300
}
}'
7. Execute code that accesses mounted files:
curl -X POST http://localhost:8000/execute \
-H "Content-Type: application/json" \
-d '{
"code": "import os\nprint(\"Files in mounted directory:\")\nfor file in os.listdir(\"/data/downloads\"):\n print(f\" - {file}\")",
"session_id": "YOUR_SESSION_ID"
}'
```
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"codebox-ai": {
"codebox-ai": {
"command": "uv",
"args": [
"run",
"mcp",
"dev",
"mcp_server.py"
]
}
}
}
}McpServers
{
"codebox-ai": {
"command": "uv",
"args": [
"run",
"mcp",
"dev",
"mcp_server.py"
]
}
}A secure Python code execution service that provides a self-hosted alternative to OpenAI's Code Interpreter or Anthropic's Claude analysis tool. Built with FastAPI and IPython kernels, it supports session-based code execution and integrates with LLM function calling.
It also now supports the Model Context Protocol (MCP) for seamless integration with LLM applications.
Features
- Session-based Python code execution in Docker containers
- IPython kernel for rich output support
- Dynamic package installation with security controls
- Package allowlist/blocklist system
- Version control for security vulnerabilities
- Support for pip and conda installations
- State persistence between executions
- Support for plotting and visualization
- Code security validation
- AST-based code analysis
- Protection against dangerous imports and operations
- Support for Jupyter magic commands and shell operations
- Host directory mounting
- Mount local directories into the container
- Read-only or read-write access control
- Security validations to prevent access to sensitive paths
MCP Server (Model Context Protocol)
CodeBox-AI now supports the Model Context Protocol (MCP), allowing LLM applications (like Claude Desktop) to interact with your code execution service in a standardized way.
Running the MCP Server
You can run the MCP server in several ways:
- Standalone (for MCP clients or Claude Desktop):
uv run mcp dev mcp_server.py
This starts the MCP server in development mode for local testing and debugging.
- Register with Claude Desktop:
uv run mcp install mcp_server.py --name "CodeBox-AI"
This will make your server available to Claude Desktop as a custom tool.
- Combined FastAPI + MCP server:
uv run run.py
This starts both the FastAPI API and the MCP server (MCP available at
/mcp).
- MCP server only:
uv run run.py --mode mcp
MCP Features
- execute_code: Execute Python code and return results
- session://{session_id}: Get info about a session
- sessions://: List all active sessions
Example: Testing with MCP Inspector
1. Start the MCP server:
uv run mcp dev mcp_server.py
2. Open the MCP Inspector and connect to your local server.
Example: Registering with Claude Desktop
1. Configure the MCP server in the Claude Desktop settings:
Edit the file ~/Library/Application Support/Claude/claude_desktop_config.json. The following is an example configuration:
{
"mcpServers": {
"CodeBox-AI": {
"command": "uv",
"args": [
"run",
"--project",
"/Users/username/src/codebox-ai",
"/Users/username/src/codebox-ai/mcp_server.py",
"--mount",
"/Users/username/Downloads"
]
}
}
}
Unfortunately, all paths need to be absolute. This example shows how to mount the Downloads directory into the container.
2. Open Claude Desktop and the server should appear as a custom tool.
Prerequisites
- Python 3.9+
- Docker
- uv - Fast Python package installer and resolver
Installation
1. Clone the repository:
git clone https://github.com/yourusername/codebox-ai.git
cd codebox-ai
2. Install dependencies with uv:
```bash
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
