Skip to main content
Glama

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.

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 --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

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

Available Tools

4 tools
shellA

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

    A4.1/5.0

    Scored across 4 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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 npm
      6
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides 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 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides 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 npm
      MIT