Microsandbox MCP Server for Claude

Content

The Microsandbox MCP server exposes the Microsandbox runtime to Claude and other MCP-capable clients over stdio. It gives agents structured tools for creating microVM sandboxes, running commands inside them, reading and writing sandbox files, managing named volumes, and inspecting resource metrics.

This entry is for workflows where Claude needs an isolated execution target, not direct access to the host shell. The practical safety boundary still depends on how the sandbox is configured: what image it uses, whether it is ephemeral or persistent, which volumes are attached, which secrets are available, and what network policy is active.

Microsandbox documents the MCP server in its AI agents guide, publishes the server as the microsandbox-mcp npm package, and maintains the source in the superradcompany/microsandbox-mcp repository.

Features

• Stdio MCP server installable with npx -y microsandbox-mcp.
• Sandbox lifecycle tools for creating, listing, inspecting, stopping, and removing sandboxes.
• Ephemeral sandbox_run tool for creating a sandbox, running a command, and cleaning it up.
• Command execution tools for command-plus-args execution and shell-string execution inside an existing sandbox.
• Filesystem tools for reading, writing, listing, creating, removing, and statting files inside the sandbox filesystem.
• Named volume tools for creating, listing, and removing persistent volumes.
• Metrics tools for live CPU, memory, disk I/O, and network visibility.
• Runtime installation check for the local msb runtime and libkrunfw.
• Client examples for Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, OpenCode, Zed, and other stdio-capable MCP clients.
• Microsandbox runtime support for macOS on Apple Silicon and Linux on x86_64 or ARM64 with KVM support.

Use Cases

• Give Claude a disposable microVM for running untrusted snippets, tests, or package experiments without handing it the host shell directly.
• Run commands in a known sandbox image while keeping stdout, stderr, and exit codes available to the agent.
• Let Claude inspect or edit files inside a sandboxed workspace before copying only approved artifacts back into a project.
• Create persistent sandboxes for repeatable debugging sessions that need state across multiple tool calls.
• Attach named volumes when a workflow needs cached dependencies or reusable data between sandbox runs.
• Monitor CPU, memory, disk I/O, and network metrics for long-running sandboxed tasks.
• Test code that needs outbound internet access while relying on Microsandbox's host-controlled network policy for local-network and metadata-endpoint boundaries.

Installation

Claude Code

1. Confirm Node.js 22+ is installed:

node --version

1. Add the stdio MCP server:

claude mcp add --transport stdio microsandbox -- npx -y microsandbox-mcp

1. Start a fresh Claude Code session and inspect the available Microsandbox tools before approving any execution request.
2. Run the check_installed tool first. If the host runtime is missing, follow the Microsandbox installation docs for the msb runtime and libkrunfw.

Claude Desktop

1. Open the Claude Desktop MCP configuration file.
2. Add the microsandbox server configuration shown below.
3. Restart Claude Desktop.
4. Start with low-risk prompts such as checking whether the runtime is installed or creating a short-lived sandbox for a simple command.

Configuration

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

For clients that expect the server object directly, use the same command and arguments:

{
  "microsandbox": {
    "command": "npx",
    "args": ["-y", "microsandbox-mcp"]
  }
}

Examples

Check the runtime

Ask Claude to verify that the local Microsandbox runtime is available before running any sandboxed code.

Check whether Microsandbox is installed and report what runtime pieces are missing.

Run an ephemeral command

Use an ephemeral sandbox when the task does not need state after the command finishes.

Create a temporary Microsandbox Python sandbox, run a hello-world command, return stdout and stderr, and clean up the sandbox afterward.

Inspect sandbox state

Use lifecycle and metrics tools for a persistent sandbox during a debugging session.

List the running Microsandbox sandboxes, inspect the one named "agent-test", and show current CPU, memory, disk I/O, and network metrics.

Work with sandbox files

Keep file operations scoped to the sandbox filesystem.

Create a file inside the sandbox, run a command that reads it, then show me the output and the final file metadata.

Best Practices

• Prefer sandbox_run for disposable tasks that should not keep state.
• Use persistent sandboxes only when the workflow genuinely needs continuity.
• Name sandboxes and volumes clearly so cleanup decisions are obvious.
• Keep network access narrow for workflows involving private code, credentials, datasets, or customer data.
• Review shell-string commands before approval because sandbox_shell supports pipes, redirects, and shell syntax.
• Avoid passing secrets as command arguments or prompts. Use the Microsandbox secret-injection model and narrow allowed hosts when secrets are required.
• Clean up unused sandboxes and volumes after each workflow.
• Treat output from sandboxed code as untrusted input, especially when it comes from downloaded packages, web content, tests, or generated files.

Troubleshooting

Runtime check reports missing components

Run the MCP check_installed tool first, then follow the Microsandbox install docs for the host operating system. Linux hosts need KVM support; macOS support is for Apple Silicon.

Sandbox creation fails

Confirm the host platform is supported, the runtime is installed, the user has permission to run it, and there is enough disk space for images and writable layers.

Commands hang or produce no output

Use explicit command arguments where possible, add a timeout, and inspect stdout, stderr, and the exit code. For shell syntax, confirm the target image has the expected shell and binaries installed.

Network access is blocked

Review the Microsandbox networking docs and the active sandbox policy. The default network model is designed to prevent workloads from reaching private network ranges, loopback, link-local addresses, cloud metadata endpoints, and DNS rebinding targets.

Files disappear between runs

Ephemeral sandboxes are meant to be disposable. Use a persistent named sandbox, snapshot, or named volume only when retaining state is intentional.

Related Links

• Microsandbox AI agents guide
• Microsandbox MCP repository
• microsandbox-mcp on npm
• Microsandbox documentation
• Microsandbox security model
• Microsandbox secrets documentation