shell-mcp

An MCP server for Claude Code and GitHub Copilot that runs your agent's shell commands inside a microsandbox Linux sandbox instead of on your Windows or Mac machine. Your project folder is mounted into the sandbox, so file tools keep working on the host while every command runs in Linux.

It exposes four tools: shell (foreground or background commands with a timeout), shell_output, shell_kill and shell_list. Paths are translated between the host folder and the sandbox mount, and the working directory is kept across calls.

Published on npm as @edorosh/shell-mcp.

Requirements

• Windows (x64 or arm64) or macOS on Apple Silicon, with Node.js 22 or newer (arm64 Node on a Mac).
• bash in the sandbox image (ubuntu:24.04 has it). shell-mcp creates the sandbox itself, or attaches to one you made (see Sandbox and runtime).
• msb 0.7.11, matching the SDK that shell-mcp 1.2.0 pins. Without a separate install, the runtime packaged with the SDK is used.

Quick start

New to microsandbox? Typical setups has ready-to-copy configurations: no internet, package registries only, full internet, extra folders, a bigger machine.

1. Check the setup, and do the first image pull in a terminal (the sandbox is created on first use and keeps running after the client exits):

npx -y @edorosh/shell-mcp@1.2.0 --sandbox myproj --image ubuntu:24.04 --mount C:\Users\<you>\dev\myproj:/workspace --prepare

npx -y @edorosh/shell-mcp@1.2.0 --sandbox myproj --image ubuntu:24.04 --mount /Users/<you>/dev/myproj:/workspace --prepare

Always use the scoped name with a version. npx shell-mcp is an unrelated package.

2. Add it to your client. Claude Code, in the project's .mcp.json:

{
  "mcpServers": {
    "sandbox": {
      "command": "cmd",
      "args": [
        "/c", "npx", "-y", "@edorosh/shell-mcp@1.2.0",
        "--sandbox", "myproj",
        "--image", "ubuntu:24.04",
        "--mount", "C:\\Users\\<you>\\dev\\myproj:/workspace"
      ]
    }
  }
}

and turn off the built-in shell in .claude/settings.json:

{ "permissions": { "deny": ["Bash"] } }

On a Mac, use "command": "npx" with "-y", "@edorosh/shell-mcp@1.2.0", ... and "/Users/<you>/dev/myproj:/workspace" as the mount (see Client setup).

For GitHub Copilot in VS Code (.vscode/mcp.json plus a hook that blocks its built-in shell) and the Copilot CLI, see Client setup. Ready-made files are in examples/.

3. Verify: ask the agent to run uname -a. It should report Linux.

Documentation

• Typical setups: ready-to-copy configurations for people new to microsandbox.
• Sandbox and runtime: creating a sandbox, msb versions, upgrading.
• Client setup: Claude Code, GitHub Copilot, Copilot CLI, client timeouts.
• Configuration: all flags and environment variables, --check, global install.
• Troubleshooting
• Known issues and limitations
• CHANGELOG.md and ROADMAP.md

Contributing

npm ci
npm test
npm run build

See Development for the integration suite against a real sandbox and platform pitfalls, releasing.md for releases, and the product spec for the requirements. Coding agents read AGENTS.md.

License

MIT