# Shell Mcp

> A Model Context Protocol (MCP) server that provides secure shell command execution

- **Type:** MCP server
- **Install:** `agentstack add mcp-zatevakhin-shell-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [zatevakhin](https://agentstack.voostack.com/s/zatevakhin)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [zatevakhin](https://github.com/zatevakhin)
- **Source:** https://github.com/zatevakhin/shell-mcp

## Install

```sh
agentstack add mcp-zatevakhin-shell-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# shell-mcp

A Model Context Protocol (MCP) server that provides secure shell command execution with advanced command whitelisting, user confirmation, and comprehensive security controls. Designed for developers and LLM agents, it provides a safe and flexible way to run shell commands over multiple transports.

## Features

- Execute shell commands via MCP protocol with comprehensive validation
- Advanced command whitelisting with flexible allow/deny policies
- User confirmation for non-whitelisted commands (using MCP elicitation, if available on client)
- Support for multiple transports (stdio, SSE, streamable HTTP)
- Timeout protection prevents hanging processes
- Context-aware error messages with detailed information for agents
- Shell feature restrictions (pipes, redirects, substitutions, etc.)

## Installation

### Via Nix

```bash
nix run github:zatevakhin/shell-mcp
```

Or run specific version you need.
```bash
nix run "github:zatevakhin/shell-mcp?ref="
```

### Via Cargo

```bash
cargo install --git https://github.com/zatevakhin/shell-mcp.git
```
> Should work for most systems.

## Usage

### Basic Usage

```bash
# Run with stdio transport (default)
shell-mcp

# Run with SSE server
shell-mcp --transport sse --bind 127.0.0.1:3003

# Run with streamable HTTP
shell-mcp --transport streamable-http --bind 127.0.0.1:3003
```

### Configuration

#### Command Security Policies

**Traditional Whitelist (Default):**
```bash
SHELL_COMMANDS="ls,cat,grep,find,echo,pwd,git" shell-mcp
```
> If not set, defaults to: `ls,cat,grep,find,echo,pwd`

**Allow All Commands with Exceptions:**
```bash
SHELL_COMMANDS="*" SHELL_DISABLED_COMMANDS="rm,dd,sudo,shutdown" shell-mcp
```

**Enhanced Default Security:**
```bash
SHELL_DISABLED_COMMANDS="rm,dd" shell-mcp
```

#### Shell Feature Controls

**Disable Specific Features:**
```bash
SHELL_DISABLE_FEATURES="pipes,substitutions" shell-mcp
```

**Enable Only Specific Features:**
```bash
SHELL_FEATURES="pipes,logical-ops" shell-mcp
```

#### Other Settings

**Set timeout:**
```bash
SHELL_MCP_TIMEOUT=60 shell-mcp
```
> If not set, defaults to 30 seconds.

**Control startup display:**
```bash
SHELL_MCP_STARTUP_INFO=false shell-mcp
```
> If not set, startup information is shown by default.

**Verbose logging (request/response):**
```bash
# Log each incoming shell command and the returned result
shell-mcp -v

# Also enable debug-level logs (includes validated shell command)
shell-mcp -vv
```
> Logs are written to stderr. `RUST_LOG` takes precedence over `-v/-vv`.

### Error Handling

The server provides detailed, context-aware error messages:

**Command Not Allowed:**
```
Command blocked: Command 'rm' is not in the allowed list

Available Commands:
  cat, echo, find, grep, ls, pwd
```

**Command Explicitly Disabled:**
```
Command blocked: Command 'rm' is explicitly disabled
```

**Feature Disabled:**
```
Command blocked: Pipes are disabled

Shell Features Status:
  Pipes (|): disabled
  Logical operators (&& ||): enabled
  Semicolons (;): enabled
  Input redirects (): enabled
  Command substitutions ($(command)): enabled
```

### MCP Tool

The server provides a `shell` tool that accepts:

- `command`: The shell command to execute (with comprehensive validation)

The default working directory for all commands is controlled via the CLI `-w/--workdir` flag.
The tool provides enhanced error reporting with security context and user confirmation via elicitation (if available on client) for non-whitelisted commands.

## Security

- Advanced command whitelisting with flexible allow/deny policies
- User confirmation for non-whitelisted commands via MCP elicitation (if available on client)
- Shell feature restrictions (pipes, redirects, substitutions, etc.)
- Context-aware error messages with detailed information
- Shell commands are executed after parsing the input into an Abstract Syntax Tree (AST) for comprehensive validation and generation into safe shell code.
- Timeout protection prevents hanging processes
- Working directory can be set (**but not limited**) via the CLI `--workdir` flag

**Note:** While robust, the security features are not foolproof and can be bypassed by advanced users with malicious intent (e.g., exploiting misconfigured policies). current implementation should be enough to keep LLM agents guided by policies and prevent misuse by non-advanced users.

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [zatevakhin](https://github.com/zatevakhin)
- **Source:** [zatevakhin/shell-mcp](https://github.com/zatevakhin/shell-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-zatevakhin-shell-mcp
- Seller: https://agentstack.voostack.com/s/zatevakhin
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.