MCP Sandbox

MCP Sandbox

Sinta-se à vontade para experimentar no mcp sandbox

中文文档 | English

Demonstração

Python MCP Sandbox é uma ferramenta interativa de execução de código Python que permite que usuários e LLMs executem código Python com segurança e instalem pacotes em contêineres Docker isolados.

Viby

Viby funciona com o mcp sandbox

Recursos

• 🐳 Isolamento Docker: Execute código Python com segurança em contêineres Docker isolados
• 📦 Gerenciamento de Pacotes: Instale e gerencie pacotes Python facilmente com suporte para espelhos PyPI personalizados
• 📊 Geração de Arquivos: Suporte para gerar arquivos e acessá-los por meio de links web
• 🔐 Autenticação: Autenticação opcional baseada em chave de API para ambientes multiusuário
• 🎨 Interface Web: Interface web integrada para gerenciar sandboxes e visualizar resultados de execução
• 🌐 Suporte SSE: Comunicação em tempo real via Server-Sent Events para integração com MCP

Instalação

# Clone the repository
git clone https://github.com/JohanLi233/python-mcp-sandbox.git
cd python-mcp-sandbox

# Install dependencies using uv
uv venv
uv sync

# Start the server
uv run main.py

O endpoint SSE padrão é http://127.0.0.1:8181/sse, e você pode interagir com ele por meio do MCP Inspector via SSE ou qualquer outro cliente que suporte conexões SSE.

Configuração

A configuração do servidor pode ser personalizada em config.toml:

• Host: O padrão é 127.0.0.1 (somente localhost)
• Porta: O padrão é 8181
• Espelho PyPI: Configure seu índice de espelho de pacotes Python preferido

Para permitir acesso externo, altere o host para 0.0.0.0 no arquivo de configuração.

Ferramentas Disponíveis

1. create_sandbox: Cria um novo sandbox Python Docker e retorna seu ID para execução subsequente de código e instalação de pacotes
2. list_sandboxes: Lista todos os sandboxes existentes (contêineres Docker) para reutilização
3. execute_python_code: Executa código Python em um sandbox Docker especificado
4. install_package_in_sandbox: Instala pacotes Python em um sandbox Docker especificado
5. check_package_installation_status: Verifica se um pacote está instalado ou o status da instalação em um sandbox Docker
6. execute_terminal_command: Executa um comando de terminal no sandbox Docker especificado. Parâmetros: sandbox_id (string), command (string). Retorna stdout, stderr, exit_code.
7. upload_file_to_sandbox: Envia um arquivo local para o sandbox Docker especificado. Parâmetros: sandbox_id (string), local_file_path (string), dest_path (string, opcional, padrão: /app/results).

Estrutura do Projeto

python-mcp-sandbox/
├── main.py                    # Application entry point
├── requirements.txt           # Project dependencies
├── Dockerfile                 # Docker configuration for Python containers
├── results/                   # Directory for generated files
├── mcp_sandbox/               # Main package directory
│   ├── __init__.py
│   ├── models.py              # Pydantic models
│   ├── api/                   # API related components
│   │   ├── __init__.py
│   │   └── routes.py          # API route definitions
│   ├── core/                  # Core functionality
│   │   ├── __init__.py
│   │   ├── docker_manager.py  # Docker container management
│   │   └── mcp_tools.py       # MCP tools
│   └── utils/                 # Utilities
│       ├── __init__.py
│       ├── config.py          # Configuration constants
│       ├── file_manager.py    # File management
│       └── task_manager.py    # Periodic task management
└── README.md                  # Project documentation

Exemplo de Prompt

I've configured a Python code execution sandbox for you. You can run Python code using the following steps:

1. First, use the "list_sandboxes" tool to view all existing sandboxes (Docker containers).
   - You can reuse an existing sandbox_id if a sandbox exists, do not create a new one.
   - If you need a new sandbox, use the "create_sandbox" tool.
   - Each sandbox is an isolated Python environment, and the sandbox_id is required for all subsequent operations.

2. If you need to install packages, use the "install_package_in_sandbox" tool
   - Parameters: sandbox_id and package_name (e.g., numpy, pandas)
   - This starts asynchronous installation and returns immediately with status

3. After installing packages, you can check their installation status using the "check_package_installation_status" tool
   - Parameters: sandbox_id and package_name (name of the package to check)
   - If the package is still installing, you need to check again using this tool

4. Use the "execute_python_code" tool to run your code
   - Parameters: sandbox_id and code (Python code)
   - Returns output, errors and links to any generated files
   - All generated files are stored inside the sandbox, and file_links are direct HTTP links for inline viewing

Example workflow:
- Use list_sandboxes to check for available sandboxes, if no available sandboxes, use create_sandbox to create a new one → Get sandbox_id
- Use install_package_in_sandbox to install necessary packages (like pandas, matplotlib), with the sandbox_id parameter
- Use check_package_installation_status to verify package installation, with the same sandbox_id parameter
- Use execute_python_code to run your code, with the sandbox_id parameter

Code execution happens in a secure sandbox. Generated files (images, CSVs, etc.) will be provided as direct HTTP links, which can viewed inline in the browser.

Remember not to use plt.show() in your Python code. For visualizations:
- Save figures to files using plt.savefig() instead of plt.show()
- For data, use methods like df.to_csv() or df.to_excel() to save as files
- All saved files will automatically appear as HTTP links in the results, which you can open or embed directly.

Exemplo de Configuração MCP

Abaixo está um exemplo de configuração para o Claude Desktop:

{
  "mcpServers": {
    "mcpSandbox": {
      "command": "npx",
      "args": ["-y", "supergateway", "--sse",  "http://127.0.0.1:8181/sse"]
    }
  }
}

Se a autenticação estiver habilitada, inclua a chave de API:

{
  "mcpServers": {
    "mcpSandbox": {
      "command": "npx",
      "args": ["-y", "supergateway", "--sse",  "http://127.0.0.1:8181/sse?api_key=<YOUR_API_KEY>"]
    }
  }
}

Exemplo de Configuração MCP para Demonstração Online

{
  "mcpServers": {
    "mcpSandbox": {
      "command": "npx",
      "args": ["-y", "supergateway", "--sse",  "http://115.190.87.78/sse?api_key=<API_KEY>"]
    }
  }
}

Modifique o serverUrl conforme necessário para o seu ambiente.