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
- Author
- tomconte
- GitHub stars
- 9
- Downloads
- 287
- Categories
- AI
Jump to
- Session-based Python code execution in Docker containers
- IPython kernel for rich output and plotting support
- Dynamic package installation with allowlist/blocklist and version controls
- State persistence between executions in the same session
- AST-based code security validation and dangerous import protection
- Host directory mounting with read-only or read-write access control
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
Clone the repository, install dependencies with uv sync, and start the server with uv run -m codeboxai.main. Optionally run the MCP server standalone with uv run mcp dev mcp_server.py, register it with Claude Desktop via uv run mcp install mcp_server.py --name "CodeBox-AI", or start both FastAPI and MCP servers together with uv run run.py. Use the REST API endpoints (POST /sessions, POST /execute, etc.) or the MCP tools (execute_code, session://{session_id}, sessions://) for code execution.
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"
]
}
}CodeBox-AI
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.
