shell-mcp
Integrates with GitHub Copilot (VS Code) to allow it to execute shell commands within a defined sandbox, enabling agents to perform local code operations and project tasks.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@shell-mcp run the test suite in the sandbox and show any failures"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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).
bashin the sandbox image (ubuntu:24.04has it). shell-mcp creates the sandbox itself, or attaches to one you made (see Sandbox and runtime).msb0.7.11, matching the SDK that shell-mcp 1.2.0 pins. Without a separate install, the runtime packaged with the SDK is used.
Related MCP server: Run Command MCP Server
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 --preparenpx -y @edorosh/shell-mcp@1.2.0 --sandbox myproj --image ubuntu:24.04 --mount /Users/<you>/dev/myproj:/workspace --prepareAlways 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,
msbversions, upgrading.Client setup: Claude Code, GitHub Copilot, Copilot CLI, client timeouts.
Configuration: all flags and environment variables,
--check, global install.
Contributing
npm ci
npm test
npm run buildSee 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
Available Tools
4 toolsshellA
Run a shell command (bash) inside an isolated Linux sandbox, not on the host machine. The host directory /app is mounted in the sandbox at /workspace; the command starts in /workspace and only files under that directory are shared with the host. The working directory persists between calls, but environment variables and shell state (aliases, functions) do not. Do not rely on cd across parallel calls: each starts in the directory current when it starts, and the last to finish sets it. Default timeout is 120 seconds, maximum 600 seconds (timeout_ms). Use run_in_background for servers and other long-running processes; it returns a job id to use with shell_output, shell_kill and shell_list. Interactive programs (editors, pagers, prompts waiting for input) are not supported. Paths in output under /workspace are shown as host paths under /app. To read or edit files, use your file tools with host paths (/app) rather than shell commands.
Inputs: command (required), timeout_ms, description, run_in_background.
shell_killA
Stop a background job started with shell and report whether it has stopped.
Inputs: job_id (required).
shell_listA
List background jobs started in this session, with their state and command.
Inputs: no named parameters.
shell_outputA
Read new output from a background job started with shell, since the last call. Reports whether the job is still running and its exit code once finished.
Inputs: job_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
The four tools have clearly distinct roles: `shell` starts commands and jobs, while `shell_output`, `shell_kill`, and `shell_list` operate specifically on background jobs. There is minimal risk of confusing foreground command execution with background job management.
All tools share the `shell` prefix, and background job operations follow a consistent `shell_<operation>` pattern. The main `shell` tool is the only slight deviation, but it is still readable and predictable.
Four tools is well scoped for a sandboxed shell server: one execution tool plus three focused background-job controls. Each tool earns its place without redundant surface area.
The tool set covers foreground execution, background job launch, output streaming, termination, and listing. Given the stated non-support for interactive programs, no obvious lifecycle gaps remain.
Maintenance
Related MCP Connectors
Start, pause, resume, and run commands and file operations in Linux sandboxes.
Linux microVM sandboxes for AI agents: run commands, files, processes, pause and wake.
Manage Sprites: sandboxed compute environments with exec, services, and checkpoints.
Secure Linux sandboxes for AI agents, as MCP tools.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables secure execution of shell commands and file operations within isolated Docker containers. Provides process management, interactive input handling, and comprehensive file system operations for containerized development environments.101 npm6MIT
- AlicenseNot gradedqualityDmaintenanceProvides tools for executing shell commands both synchronously and asynchronously with real-time output streaming and process management capabilities. It enables users to start background tasks, monitor progress, and manage long-running processes via Stdio or HTTP transports.547 npmMIT
- AlicenseNot gradedqualityCmaintenanceProvides a secure environment for executing shell commands with restricted directory access and timeout enforcement. It includes tools for running commands, managing execution history, and isolating environment variables.24 npmMIT
- AlicenseNot gradedqualityCmaintenanceProvides a restricted Docker-based sandbox for LLM agents, enabling file operations, command execution, and local Git within an isolated runtime.19 npmMIT