Gru Sandbox MCP server

gbox is a self-hostable sandbox for AI agents that allows them to execute commands, browse the web, and interact with desktop/mobile environments. It provides an MCP (Model Context Protocol) server that integrates directly with MCP clients like Claude Desktop and Cursor, enabling AI models to perform a wide range of real-world tasks.

Installation

System Requirements

• macOS 10.15 or later
• Docker Desktop for Mac
• Homebrew

Installation Steps

# Install via Homebrew
brew tap babelcloud/gru && brew install gbox

# Initialize environment
gbox setup

# Export MCP config and merge into Claude Desktop
gbox mcp export --merge-to claude
# or gbox mcp export --merge-to cursor

# Restart Claude Desktop

Update Steps

# Update gbox to the latest version
brew update && brew upgrade gbox

# Update the environment
gbox setup

# Export and merge latest MCP config into Claude Desktop
gbox mcp export --merge-to claude
# or gbox mcp export --merge-to cursor

# Restart Claude Desktop

Usage

Command Line Usage

The gbox command-line tool allows you to manage sandbox containers:

# Cluster management
gbox cluster setup    # Setup cluster environment
gbox cluster cleanup  # Cleanup cluster environment

# Container management
gbox box create --image python:3.9 --env "DEBUG=true" -w /app -v /host/path:/app   # Create container
gbox box list                                                                      # List containers
gbox box start <box-id>                                                            # Start container
gbox box stop <box-id>                                                             # Stop container
gbox box delete <box-id>                                                           # Delete container
gbox box exec <box-id> -- python -c "print('Hello')"                               # Execute command
gbox box inspect <box-id>                                                          # Inspect container

# MCP configuration
gbox mcp export                          # Export MCP configuration
gbox mcp export --merge-to claude        # Export and merge into Claude Desktop config
gbox mcp export --dry-run                # Preview merge result without applying changes

Using Volume Mounts

You can share files between your host system and the sandbox containers using volume mounts:

# Basic bind mount
gbox box create -v /data:/data --image python:3.9

# Read-only bind mount
gbox box create -v /data:/data:ro

# Multiple bind mounts
gbox box create \
  -v /config:/etc/myapp \
  -v /data:/var/lib/myapp:ro \
  -v /logs:/var/log/myapp:ro:rprivate \
  --image python:3.9

The volume mount syntax follows this format:

-v /host/path:/container/path[:ro][:propagation]

Where:

• /host/path: Path to a file or directory on your host system
• /container/path: Path where the file or directory will be mounted in the container
• ro (optional): Makes the mount read-only
• propagation (optional): Sets the mount propagation mode

Note: The host path must exist before creating the container.

Software Development Kits (SDKs)

Python SDK

pip install pygbox

TypeScript SDK

npm install @gru/gbox

Capabilities

gbox provides several key features:

Terminal Capabilities

• Execute any Linux command
• Run Python scripts directly
• Share session across invokes

File Management

• Mount host machine folders into sandbox
• Access sandbox files through HTTP links
• Read file content in multi-modal format
• Write and re-write files

Browser Features

• Open any URL and return content in multi-modal format
• Operate browser by instructions

MCP Use Cases

When integrated with AI clients like Claude Desktop, gbox enables:

• Generating Diagrams: Create visualizations of data such as stock prices
• Generating PDFs: Compile information into PDF format
• Analyzing and Calculation: Perform complex data analysis tasks
• Processing Local Files: Find, manipulate, and compress files on your system
• Execute Arbitrary Tasks: Perform a wide range of operations like downloading videos

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.