GitHub - philschmid/code-sandbox-mcp

https://github.com/philschmid/code-sandbox-mcp • Aug 21, 2025 20:45

Extracto

Contribute to philschmid/code-sandbox-mcp development by creating an account on GitHub.

Resumen

Resumen Principal

El Code Sandbox MCP Server es una solución ligera y basada en STDIO (entrada/salida estándar) diseñada para permitir que asistentes de inteligencia artificial y aplicaciones de LLM (Large Language Model) ejecuten fragmentos de código de forma segura en entornos aislados y contenerizados. Utilizando el paquete llm-sandbox, este servidor facilita la interacción programática sin comprometer la seguridad del sistema anfitrión. Su mecanismo de funcionamiento implica iniciar una sesión de contenedor (con herramientas como podman o docker), escribir el código en un archivo temporal, copiarlo al contenedor, ejecutar los comandos específicos del lenguaje (por ejemplo, python3 -u code.py o node -u code.js), capturar los flujos de salida y error, y finalmente devolver los resultados al cliente antes de detener y eliminar el contenedor. Ofrece herramientas clave como run_python_code y run_js_code, que permiten la ejecución de código Python y JavaScript respectivamente, convirtiéndolo en un componente esencial para la integración de capacidades de codificación dinámica en sistemas de IA avanzados.

Elementos Clave

Mecanismo de Ejecución Contenerizada: El servidor opera estableciendo una sesión de contenedor efímera para cada ejecución. El código fuente es primero escrito en un archivo temporal en el host, luego copiado al directorio de trabajo configurado dentro del contenedor. Posteriormente, se ejecutan los comandos específicos del lenguaje para compilar o interpretar el código, capturando toda la salida estándar y los errores. Una vez finalizada la ejecución, el contenedor es eliminado para garantizar un entorno limpio y seguro para futuras operaciones.
Herramientas de Ejecución Disponibles: Proporciona dos funciones principales para la ejecución de código: run_python_code y run_js_code. Ambas herramientas requieren un parámetro code (string) que contiene el fragmento de código Python o JavaScript (Node.js) a ejecutar. Estas funciones encapsulan la complejidad de la gestión del contenedor, ofreciendo una interfaz sencilla para que los clientes de MCP (Model Context Protocol) puedan invocar la ejecución de código en un sandbox seguro y aislado.
Configuración y Personalización Avanzada: El Code Sandbox MCP Server se integra en la configuración del cliente MCP, permitiendo a los usuarios especificar command y args. Además, soporta el paso de variables de entorno al sandbox mediante el flag --pass-through-env y la definición de un objeto env. Los usuarios pueden también proporcionar una imagen de contenedor personalizada configurando las variables de entorno CONTAINER_IMAGE y CONTAINER_LANGUAGE, lo que ofrece flexibilidad para añadir dependencias o personalizar el entorno de ejecución.
Integración con Plataformas de IA: El servidor está diseñado para una integración fluida con herramientas de IA, como el Gemini SDK y el Gemini CLI. A través de la configuración mcpServers en los archivos de configuración de Gemini, los modelos de IA pueden acceder a las capacidades de ejecución de código. El Gemini SDK puede pasar la sesión del cliente FastMCP como una herramienta a generate_content, habilitando así que los modelos de lenguaje invoquen la ejecución de código dinámicamente, como se ilustra en el ejemplo de ping a google.com.

Análisis e Implicaciones

Este servidor es crucial para expandir las capacidades de los LLM, permitiéndoles no solo razonar sobre el código, sino también ejecutarlo de manera confiable y segura. Facilita el desarrollo de asistentes de IA más potentes que pueden interactuar con el mundo real a través de la programación, abriendo puertas a aplicaciones que requieren cálculo, validación o manipulación de datos en tiempo real.

Contexto Adicional

El repositorio incluye imágenes de contenedor predefinidas para Python y Node.js, publicadas en Docker Hub, que sirven como base. Además, el sistema permite a los usuarios construir y personalizar sus propias imágenes de contenedor a partir de Dockerfiles, ofreciendo total control sobre el entorno de ejecución para satisfacer requisitos específicos.

Contenido

Code Sandbox MCP Server

The Code Sandbox MCP Server is a lightweight, STDIO-based Model Context Protocol (MCP) Server, allowing AI assistants and LLM applications to safely execute code snippets using containerized environments. It is uses the llm-sandbox package to execute the code snippets.

How It Works:

Starts a container session (podman, docker, etc.) and ensures the session is open.
Writes the code to a temporary file on the host.
Copies this temporary file into the container at the configured workdir.
Executes the language-specific commands to run the code, e.g. python python3 -u code.py or javascript node -u code.js
Captures the output and error streams from the container.
Returns the output and error streams to the client.
Stops and removes the container.

Available Tools:

run_python_code - Executes a snippet of Python code in a secure, isolated sandbox.
- code (string, required): The Python code to execute.
run_js_code - Executes a snippet of JavaScript (Node.js) code in a secure, isolated sandbox.
- code (string, required): The JavaScript code to execute.

Installation

pip install git+https://github.com/philschmid/code-sandbox-mcp.git

Getting Started: Usage with an MCP Client

Examples:

Local Client Python example for running python code
Gemini SDK example for running python code with the Gemini SDK
Calling Gemini from a client example for running python code that uses the Gemini SDK and passes through the Gemini API key
Local Client Javascript example for running javascript code

To use the Code Sandbox MCP server, you need to add it to your MCP client's configuration file (e.g., in your AI assistant's settings). The server is designed to be launched on-demand by the client.

Add the following to your mcpServers configuration:

{
  "mcpServers": {
    "code-sandbox": {
      "command": "code-sandbox-mcp",
    }
  }
}

Provide Secrets and pass through environment variables

You can pass through environment variables to the sandbox by setting the --pass-through-env flag when starting the MCP server and providing the env when starting the server

{
  "mcpServers": {
    "code-sandbox": {
      "command": "code-sandbox-mcp",
      "args": ["--pass-through-env", "API_KEY,SECRET_TOKEN"]
      "env": {
        "API_KEY": "1234567890",
        "SECRET_TOKEN": "1234567890"
      }
    }
  }
}

Provide a custom container image

You can provide a custom container image by setting the CONTAINER_IMAGE and CONTAINER_LANGUAGE environment variables when starting the MCP server. Both variables are required as the CONTAINER_LANGUAGE is used to determine the commands to run in the container and the CONTAINER_IMAGE is used to determine the image to use.

Note: When providing a custom container image both tools will use the same container image.

{
  "mcpServers": {
    "code-sandbox": {
      "command": "code-sandbox-mcp",
      "env": {
        "CONTAINER_IMAGE": "your-own-image",
        "CONTAINER_LANGUAGE": "python" # or "javascript"
      }
    }
  }
}

Use with Gemini SDK

The code-sandbox-mcp server can be used with the Gemini SDK by passing the tools parameter to the generate_content method.

from fastmcp import Client
from google import genai
import asyncio


mcp_client = Client(
    {
        "local_server": {
            "transport": "stdio",
            "command": "code-sandbox-mcp",
        }
    }
)
gemini_client = genai.Client()


async def main():
    async with mcp_client:
        response = await gemini_client.aio.models.generate_content(
            model="gemini-2.5-flash",
            contents="Use Python to ping the google.com website and return the response time.",
            config=genai.types.GenerateContentConfig(
                temperature=0,
                tools=[mcp_client.session],  # Pass the FastMCP client session
            ),
        )
        print(response.text)

if __name__ == "__main__":
    asyncio.run(main())

Use with Gemini CLI

The code-sandbox-mcp server can be used with the Gemini CLI. You can configure MCP servers at the global level in the ~/.gemini/settings.json file or in your project's root directory, create or open the .gemini/settings.json file. Within the file, add the mcpServers configuration block.

See settings.json for an example and read more about the Gemini CLI

{
  "mcpServers": {
    "code-sandbox": {
      "command": "code-sandbox-mcp",
    }
  }
}

Customize/Build new Container Images

The repository comes with 2 container images, which are published on Docker Hub:

philschmi/code-sandbox-python:latest
philschmi/code-sandbox-js:latest

docker build -t philschmi/code-sandbox-python:latest -f containers/Dockerfile.python .
docker build -t philschmi/code-sandbox-js:latest -f containers/Dockerfile.nodejs .

The script will build the image using the current user's account. To update the images you want to use you can either pass the --python-image or --js-image flags when starting the MCP server or update the const.py file.

To push the images to Docker Hub you need to retag the images to your own account and push them.

docker tag philschmi/code-sandbox-python:latest <your-account>/code-sandbox-python:latest
docker push <your-account>/code-sandbox-python:latest

To customize or install additional dependencies you can add them to the Dockerfile and build the image again.

Testing

With MCP Inspector

Start the server with streamable-http and test your server using the MCP inspector. Alternatively start inspector and run the server with stdio.

npx @modelcontextprotocol/inspector

To run the test suite for code-sandbox-mcp and its components, clone the repository and run:

# You may need to install development dependencies first
pip install -e ".[dev]"

# Run the tests
pytest tests/

License

Code Sandbox MCP Server is open source software licensed under the MIT License.

Fuente: GitHub