| Name | mcp4modal-sandbox JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | None |
| Summary | A powerful Model Context Protocol (MCP) server for seamless cloud-based sandbox management using Modal.com |
| upload_time | 2025-07-09 11:19:21 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.12 |
| license | None |
| keywords |
ai
cloud
compute
gpu
llm
mcp
modal
sandbox
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# MCP4Modal Sandbox
A powerful Model Context Protocol (MCP) server that provides seamless cloud-based sandbox management using Modal.com. This project enables LLMs and AI assistants to spawn, manage, and interact with isolated compute environments in the cloud with full GPU support.
## Features
### Core Sandbox Management
- **Launch Sandboxes**: Create isolated Python environments with custom configurations
- **Terminate Sandboxes**: Clean resource management and controlled shutdown
- **List Sandboxes**: Monitor and track active sandbox environments
- **App Namespacing**: Organize sandboxes within Modal app namespaces
### Advanced Configuration
- **Python Versions**: Support for multiple Python versions (default: 3.12)
- **Package Management**: Install pip and apt packages during sandbox creation
- **Resource Allocation**: Configure CPU cores, memory, and execution timeouts
- **Working Directory**: Set custom working directories for sandbox environments
### GPU Support
Comprehensive GPU support for machine learning and compute-intensive workloads:
- **T4**: Entry-level GPU, ideal for inference workloads
- **L4**: Mid-range GPU for general ML tasks
- **A10G**: High-performance GPU for training (up to 4 GPUs)
- **A100-40GB/80GB**: High-end GPUs for large-scale training
- **L40S**: Latest generation GPU for ML workloads
- **H100**: Latest generation high-end GPU
- **H200**: Latest generation flagship GPU
- **B200**: Latest generation enterprise GPU
### File Operations
- **Push Files**: Upload files from local filesystem to sandboxes
- **Pull Files**: Download files from sandboxes to local filesystem
- **Read File Content**: View file contents directly without downloading
- **Write File Content**: Create and edit files within sandboxes
- **Directory Management**: Create, list, and remove directories
### Command Execution
- **Remote Execution**: Run arbitrary commands in sandbox environments
- **Output Capture**: Capture stdout, stderr, and return codes
- **Timeout Control**: Configure execution timeouts for long-running tasks
- **Performance Metrics**: Track execution time and resource usage
### Security & Environment Management
- **Secrets Management**: Inject environment variables and secrets
- **Predefined Secrets**: Reference existing secrets from Modal dashboard
- **Volume Mounting**: Attach persistent storage volumes
- **Isolated Environments**: Complete isolation between sandbox instances
### Transport Options
- **stdio**: Direct command-line interface (default)
- **streamable-http**: HTTP-based communication
- **SSE**: Server-Sent Events for real-time updates
## rerequisites
- Python 3.12+
- Modal.com account and API key
- Environment variables configured (see Configuration section)
## Installation
### Using UV (Recommended)
```bash
# Clone the repository
git clone https://github.com/milkymap/mcp4modal_sandbox.git
cd mcp4modal_sandbox
# Install dependencies
uv sync
# Install in development mode
uv pip install -e .
```
### Using Docker
#### Build the Docker Image
```bash
# Build the Docker image
docker build -t mcp4modal-sandbox f Dockerfile .
```
#### Run with stdio Transport (Default)
```bash
# Run --help to find options
docker run -it \
-e MODAL_TOKEN_ID="your_modal_token_id" \
-e MODAL_TOKEN_SECRET="your_modal_token_secret" \
mcp4modal-sandbox --help
```
## Configuration
### Environment Variables
Create a `.env` file in the project root:
```bash
# Required: Modal.com API Configuration
MODAL_TOKEN_ID="your_modal_token_id"
MODAL_TOKEN_SECRET="your_modal_token_secret"
# Optional: HTTP Transport Configuration (only needed for streamable-http/sse transports)
MCP_HOST="0.0.0.0" # Default: 0.0.0.0
MCP_PORT=8000 # Default: 8000
```
### Modal.com Setup
1. Create an account at [Modal.com](https://modal.com)
2. Generate API tokens from your Modal dashboard
3. Configure the tokens in your environment variables
### Integration with Claude Desktop
Add to your Claude Desktop configuration:
#### uvx
```json
{
"mcpServers": {
"mcp4modal-sandbox": {
"command": "uvx",
"args": [
"mcp4modal_sandbox",
"--transport", "stdio",
"--app_name", "namespace",
"--preloaded_secrets", "group0", // modal secret
"--preloaded_secrets", "group1" // modal secret
],
"env": {
"MODAL_TOKEN_ID": "",
"MODAL_TOKEN_SECRET": ""
}
}
}
}
```
#### docker
```json
{
"mcpServers": {
"mcp4modal-sandbox": {
"command": "docker",
"args": [
"run", "--rm", "-i", "--name", "modal_sandbox",
"-e", "MODAL_TOKEN_ID", "-e", "MODAL_TOKEN_SECRET",
"-v", "/path/to/volume",
"milkymap/modal_sandbox:0.1",
"--transport", "stdio",
"--app_name", "namespace",
"--preloaded_secrets", "group0",
"--preloaded_secrets", "group1"
],
"env": {
"MODAL_TOKEN_ID": "",
"MODAL_TOKEN_SECRET": ""
}
}
}
}
```
## Available Tools
The MCP server provides 11 tools for comprehensive sandbox management:
1. **`launch_sandbox`** - Create new Modal sandboxes with custom configuration (Python version, packages, GPU, secrets)
2. **`terminate_sandbox`** - Stop and clean up running sandboxes
3. **`list_sandboxes`** - List all sandboxes in an app namespace with their status
4. **`execute_command`** - Run shell commands in sandboxes and capture output
5. **`push_file_to_sandbox`** - Upload files from local filesystem to sandboxes
6. **`pull_file_from_sandbox`** - Download files from sandboxes to local filesystem
7. **`list_directory_contents`** - List contents of directories within sandboxes
8. **`make_directory`** - Create directories in sandboxes
9. **`remove_path`** - Remove files or directories from sandboxes
10. **`read_file_content_from_sandbox`** - Read file contents directly from sandboxes
11. **`write_file_content_to_sandbox`** - Write content to files within sandboxes
Raw data
{
"_id": null,
"home_page": null,
"name": "mcp4modal-sandbox",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": "milkymap <ibrahima.elmokhtar@gmail.com>",
"keywords": "ai, cloud, compute, gpu, llm, mcp, modal, sandbox",
"author": null,
"author_email": "milkymap <ibrahima.elmokhtar@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/00/0b/952fbd9d12bfdb38a36fc8d63768ee60c1f658ec23ac21700f29286f5b00/mcp4modal_sandbox-1.0.0.tar.gz",
"platform": null,
"description": "# MCP4Modal Sandbox\n\nA powerful Model Context Protocol (MCP) server that provides seamless cloud-based sandbox management using Modal.com. This project enables LLMs and AI assistants to spawn, manage, and interact with isolated compute environments in the cloud with full GPU support.\n\n## Features\n\n### Core Sandbox Management\n- **Launch Sandboxes**: Create isolated Python environments with custom configurations\n- **Terminate Sandboxes**: Clean resource management and controlled shutdown\n- **List Sandboxes**: Monitor and track active sandbox environments\n- **App Namespacing**: Organize sandboxes within Modal app namespaces\n\n### Advanced Configuration\n- **Python Versions**: Support for multiple Python versions (default: 3.12)\n- **Package Management**: Install pip and apt packages during sandbox creation\n- **Resource Allocation**: Configure CPU cores, memory, and execution timeouts\n- **Working Directory**: Set custom working directories for sandbox environments\n\n### GPU Support\nComprehensive GPU support for machine learning and compute-intensive workloads:\n- **T4**: Entry-level GPU, ideal for inference workloads\n- **L4**: Mid-range GPU for general ML tasks\n- **A10G**: High-performance GPU for training (up to 4 GPUs)\n- **A100-40GB/80GB**: High-end GPUs for large-scale training\n- **L40S**: Latest generation GPU for ML workloads\n- **H100**: Latest generation high-end GPU\n- **H200**: Latest generation flagship GPU\n- **B200**: Latest generation enterprise GPU\n\n### File Operations\n- **Push Files**: Upload files from local filesystem to sandboxes\n- **Pull Files**: Download files from sandboxes to local filesystem\n- **Read File Content**: View file contents directly without downloading\n- **Write File Content**: Create and edit files within sandboxes\n- **Directory Management**: Create, list, and remove directories\n\n### Command Execution\n- **Remote Execution**: Run arbitrary commands in sandbox environments\n- **Output Capture**: Capture stdout, stderr, and return codes\n- **Timeout Control**: Configure execution timeouts for long-running tasks\n- **Performance Metrics**: Track execution time and resource usage\n\n### Security & Environment Management\n- **Secrets Management**: Inject environment variables and secrets\n- **Predefined Secrets**: Reference existing secrets from Modal dashboard\n- **Volume Mounting**: Attach persistent storage volumes\n- **Isolated Environments**: Complete isolation between sandbox instances\n\n### Transport Options\n- **stdio**: Direct command-line interface (default)\n- **streamable-http**: HTTP-based communication\n- **SSE**: Server-Sent Events for real-time updates\n\n## rerequisites\n\n- Python 3.12+\n- Modal.com account and API key\n- Environment variables configured (see Configuration section)\n\n## Installation\n\n### Using UV (Recommended)\n```bash\n# Clone the repository\ngit clone https://github.com/milkymap/mcp4modal_sandbox.git\ncd mcp4modal_sandbox\n\n# Install dependencies\nuv sync\n\n# Install in development mode\nuv pip install -e .\n```\n\n\n### Using Docker\n\n#### Build the Docker Image\n```bash\n# Build the Docker image\ndocker build -t mcp4modal-sandbox f Dockerfile .\n```\n\n#### Run with stdio Transport (Default)\n```bash\n# Run --help to find options\ndocker run -it \\\n -e MODAL_TOKEN_ID=\"your_modal_token_id\" \\\n -e MODAL_TOKEN_SECRET=\"your_modal_token_secret\" \\\n mcp4modal-sandbox --help\n```\n\n\n## Configuration\n\n### Environment Variables\nCreate a `.env` file in the project root:\n\n```bash\n# Required: Modal.com API Configuration\nMODAL_TOKEN_ID=\"your_modal_token_id\"\nMODAL_TOKEN_SECRET=\"your_modal_token_secret\"\n\n# Optional: HTTP Transport Configuration (only needed for streamable-http/sse transports)\nMCP_HOST=\"0.0.0.0\" # Default: 0.0.0.0\nMCP_PORT=8000 # Default: 8000\n```\n\n### Modal.com Setup\n1. Create an account at [Modal.com](https://modal.com)\n2. Generate API tokens from your Modal dashboard\n3. Configure the tokens in your environment variables\n\n### Integration with Claude Desktop\n\nAdd to your Claude Desktop configuration:\n\n#### uvx \n```json\n{\n \"mcpServers\": {\n \"mcp4modal-sandbox\": {\n \"command\": \"uvx\",\n \"args\": [\n \"mcp4modal_sandbox\",\n \"--transport\", \"stdio\",\n \"--app_name\", \"namespace\",\n \"--preloaded_secrets\", \"group0\", // modal secret\n \"--preloaded_secrets\", \"group1\" // modal secret\n ],\n \"env\": {\n \"MODAL_TOKEN_ID\": \"\",\n \"MODAL_TOKEN_SECRET\": \"\"\n }\n }\n }\n}\n```\n\n\n#### docker\n```json\n{\n \"mcpServers\": {\n \"mcp4modal-sandbox\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\", \"--rm\", \"-i\", \"--name\", \"modal_sandbox\",\n \"-e\", \"MODAL_TOKEN_ID\", \"-e\", \"MODAL_TOKEN_SECRET\", \n \"-v\", \"/path/to/volume\", \n \"milkymap/modal_sandbox:0.1\", \n \"--transport\", \"stdio\",\n \"--app_name\", \"namespace\",\n \"--preloaded_secrets\", \"group0\",\n \"--preloaded_secrets\", \"group1\"\n ],\n \"env\": {\n \"MODAL_TOKEN_ID\": \"\",\n \"MODAL_TOKEN_SECRET\": \"\"\n }\n }\n }\n}\n```\n\n## Available Tools\n\nThe MCP server provides 11 tools for comprehensive sandbox management:\n\n1. **`launch_sandbox`** - Create new Modal sandboxes with custom configuration (Python version, packages, GPU, secrets)\n2. **`terminate_sandbox`** - Stop and clean up running sandboxes\n3. **`list_sandboxes`** - List all sandboxes in an app namespace with their status\n4. **`execute_command`** - Run shell commands in sandboxes and capture output\n5. **`push_file_to_sandbox`** - Upload files from local filesystem to sandboxes\n6. **`pull_file_from_sandbox`** - Download files from sandboxes to local filesystem\n7. **`list_directory_contents`** - List contents of directories within sandboxes\n8. **`make_directory`** - Create directories in sandboxes\n9. **`remove_path`** - Remove files or directories from sandboxes\n10. **`read_file_content_from_sandbox`** - Read file contents directly from sandboxes\n11. **`write_file_content_to_sandbox`** - Write content to files within sandboxes\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A powerful Model Context Protocol (MCP) server for seamless cloud-based sandbox management using Modal.com",
"version": "1.0.0",
"project_urls": {
"Documentation": "https://github.com/milkymap/mcp4modal_sandbox#readme",
"Homepage": "https://github.com/milkymap/mcp4modal_sandbox",
"Issues": "https://github.com/milkymap/mcp4modal_sandbox/issues",
"Repository": "https://github.com/milkymap/mcp4modal_sandbox"
},
"split_keywords": [
"ai",
" cloud",
" compute",
" gpu",
" llm",
" mcp",
" modal",
" sandbox"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b38a6a5841637432f0c7b0cbe5991bcbd21d3f269000137f9fceddfcc044f37f",
"md5": "7a95b68bfd0aba3a936df96b38e3f1dc",
"sha256": "5b9bde7d884be1b4afe764ea357ee9c4b4c2dcc71429fb50b048fb299790c7e0"
},
"downloads": -1,
"filename": "mcp4modal_sandbox-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7a95b68bfd0aba3a936df96b38e3f1dc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 16008,
"upload_time": "2025-07-09T11:19:20",
"upload_time_iso_8601": "2025-07-09T11:19:20.655634Z",
"url": "https://files.pythonhosted.org/packages/b3/8a/6a5841637432f0c7b0cbe5991bcbd21d3f269000137f9fceddfcc044f37f/mcp4modal_sandbox-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "000b952fbd9d12bfdb38a36fc8d63768ee60c1f658ec23ac21700f29286f5b00",
"md5": "8b220c012c5a0384410babc1072a28b7",
"sha256": "18a4ea6b764bad67d613b8b04a3e73159e06433e38bffd7c35c4e299803d016e"
},
"downloads": -1,
"filename": "mcp4modal_sandbox-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "8b220c012c5a0384410babc1072a28b7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 67718,
"upload_time": "2025-07-09T11:19:21",
"upload_time_iso_8601": "2025-07-09T11:19:21.994735Z",
"url": "https://files.pythonhosted.org/packages/00/0b/952fbd9d12bfdb38a36fc8d63768ee60c1f658ec23ac21700f29286f5b00/mcp4modal_sandbox-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-09 11:19:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "milkymap",
"github_project": "mcp4modal_sandbox#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "mcp4modal-sandbox"
}
