# sonirico/mcp-shell [Health: Active]

**Category:** 🤖 Coding Agents  
**Repository:** https://github.com/sonirico/mcp-shell  
**GitHub Stars:** 105  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/sonirico-mcp-shell

## Description
Give hands to AI. MCP server to run shell commands securely, auditably, and on demand on isolated environments like docker.

## Tools
Capabilities this server exposes over MCP:

- **read_file** — always
- **list_dir** — always
- **glob** — always
- **grep** — always
- **stat** — always
- **diff_files** — always
- **system_info** — always
- **git_status** — always
- **git_log** — always
- **git_diff** — always
- **git_show** — always
- **git_blame** — always
- **git_branches** — always
- **git_tags** — always
- **git_rev_parse** — always
- **git_ls_files** — always
- **git_stash_list** — always
- **git_remotes** — always
- **write_file** — writes_enabled
- **edit_file** — writes_enabled
- **mkdir** — writes_enabled
- **move** — writes_enabled
- **delete** — writes_enabled
- **git_add** — writes_enabled
- **git_commit** — writes_enabled
- **git_switch** — writes_enabled
- **git_restore** — writes_enabled
- **git_stash** — writes_enabled
- **run_script** — scripts

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "mcp-shell": {
    "command": "npx",
    "args": ["-y","sonirico-mcp-shell"]
  }
}
```

## Documentation

## What sonirico/mcp-shell MCP server does

The sonirico/mcp-shell MCP server gives an MCP-compatible agent one tool for executing shell commands. The tool requires a `command` string and accepts an optional `base64` boolean that encodes standard output and standard error in the response. Results include the command, status, exit code, stdout, stderr, and execution time; security details may also be returned.

It is intended for situations where an agent needs access to command-line utilities while the operator retains control over which commands can run. Docker is supported as a deployment option, and the example mounts a workspace into the container.

## How it works

By default, the server starts in secure mode even when no configuration file is present. This mode does not invoke a shell interpreter. It parses the input and accepts only one fully literal simple command, rejecting shell features such as pipes, command lists, substitutions, redirections, and globs.

Allowed executables must be listed in policy and must also be classified as safe. Built-in examples include read-oriented utilities such as `ls`, `cat`, `grep`, `find`, `head`, and `tail`. Some commands, including `git`, `find`, `sort`, and `uniq`, use argument policies that permit only explicitly approved options or operations. Interpreters and wrappers such as `bash`, `python`, `env`, `timeout`, and `xargs` are rejected in secure mode, even if added to the allowlist.

The policy can also set blocked argument patterns, a maximum execution duration, a maximum output size, a working directory, and audit logging. The sonirico/mcp-shell MCP server can therefore apply command and resource restrictions before execution, but secure mode is an early-rejection layer rather than a complete sandbox.

## Setup and configuration

The project provides a Docker image and a source-based installation path. A basic Docker invocation is:

```bash
docker run -it --rm -v /tmp/mcp-workspace:/tmp/mcp-workspace sonirico/mcp-shell:latest
```

When building from source, the documented sequence clones the repository, runs `make install`, and starts `mcp-shell`.

Set `MCP_SHELL_SEC_CONFIG_FILE` to load a YAML security policy instead of relying on the built-in secure defaults. `MCP_SHELL_ALLOW_UNSAFE=true` disables validation and permits unrestricted execution; the project explicitly warns against using this setting in production. Logging can be adjusted with `MCP_SHELL_LOG_LEVEL`, `MCP_SHELL_LOG_FORMAT`, and `MCP_SHELL_LOG_OUTPUT`.

Claude Desktop can connect through a Docker stdio configuration. A custom policy file can be mounted into the container and selected with `MCP_SHELL_SEC_CONFIG_FILE`.

## Tools and capabilities

The sonirico/mcp-shell MCP server provides one shell-command execution tool with these inputs:

- `command`: required command text.
- `base64`: optional boolean for encoding stdout and stderr.

Configuration supports executable allowlists, command-string policies in legacy mode, blocked patterns, execution timeouts, output limits, working-directory selection, and audit logging. Secure mode is the recommended policy. Legacy mode enables shell execution and uses allowlists or blocklists over command strings, so its injection risk depends on the policy.

## Limitations and notes

Unrestricted execution is available only through an explicit environment-variable opt-in and is dangerous outside local development. Secure mode does not itself provide process isolation. The Docker image runs as a non-root user on Alpine, but the documentation recommends additional operating-system controls such as a read-only filesystem and dropped capabilities for defense in depth.

Git handling is restricted to read-only subcommands, with diff and text conversion drivers suppressed and a minimal environment. Child processes do not inherit server or `.env` secrets. The repository directs users to its security documentation for the detailed threat model and vulnerability-reporting scope.

_Full upstream README: https://allmcps.com/mcp/sonirico-mcp-shell/readme_