A secure shell command execution server implementing the Model Context Protocol (MCP). This server allows remote execution of whitelisted shell commands with support for stdin input. Secure Command Execution: Only whitelisted commands can be executed Standard Input Support: Pass input to commands via stdin Comprehensive Output: Returns stdout, stderr, exit status, and execution time Shell Operator
Add this skill
npx mdskills install tumf/mcp-shell-serverWell-documented MCP server with strong security whitelist approach and comprehensive examples
1# MCP Shell Server23[](https://codecov.io/gh/tumf/mcp-shell-server)4[](https://smithery.ai/server/mcp-shell-server)56[](https://mseep.ai/app/tumf-mcp-shell-server)78A secure shell command execution server implementing the Model Context Protocol (MCP). This server allows remote execution of whitelisted shell commands with support for stdin input.910<a href="https://glama.ai/mcp/servers/rt2d4pbn22"><img width="380" height="200" src="https://glama.ai/mcp/servers/rt2d4pbn22/badge" alt="mcp-shell-server MCP server" /></a>1112<a href="https://glama.ai/mcp/servers/rt2d4pbn22"><img width="380" height="200" src="https://glama.ai/mcp/servers/rt2d4pbn22/badge" alt="mcp-shell-server MCP server" /></a>1314## Features1516* **Secure Command Execution**: Only whitelisted commands can be executed17* **Standard Input Support**: Pass input to commands via stdin18* **Comprehensive Output**: Returns stdout, stderr, exit status, and execution time19* **Shell Operator Safety**: Validates commands after shell operators (; , &&, ||, |)20* **Timeout Control**: Set maximum execution time for commands2122## MCP client setting in your Claude.app2324### Published version2526```shell27code ~/Library/Application\ Support/Claude/claude_desktop_config.json28```2930```json31{32 "mcpServers": {33 "shell": {34 "command": "uvx",35 "args": [36 "mcp-shell-server"37 ],38 "env": {39 "ALLOW_COMMANDS": "ls,cat,pwd,grep,wc,touch,find"40 }41 },42 }43}44```4546### Local version4748#### Configuration4950```shell51code ~/Library/Application\ Support/Claude/claude_desktop_config.json52```5354```json55{56 "mcpServers": {57 "shell": {58 "command": "uv",59 "args": [60 "--directory",61 ".",62 "run",63 "mcp-shell-server"64 ],65 "env": {66 "ALLOW_COMMANDS": "ls,cat,pwd,grep,wc,touch,find"67 }68 },69 }70}71```7273#### Installation7475### Installing via Smithery7677To install Shell Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/mcp-shell-server):7879```bash80npx -y @smithery/cli install mcp-shell-server --client claude81```8283### Manual Installation8485### Installing via Smithery8687To install Shell Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/mcp-shell-server):8889```bash90npx -y @smithery/cli install mcp-shell-server --client claude91```9293### Manual Installation9495```bash96pip install mcp-shell-server97```9899### Installing via Smithery100101To install Shell Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/mcp-shell-server):102103```bash104npx -y @smithery/cli install mcp-shell-server --client claude105```106107## Usage108109### Starting the Server110111```bash112ALLOW_COMMANDS="ls,cat,echo" uvx mcp-shell-server113# Or using the alias114ALLOWED_COMMANDS="ls,cat,echo" uvx mcp-shell-server115```116117The `ALLOW_COMMANDS` (or its alias `ALLOWED_COMMANDS` ) environment variable specifies which commands are allowed to be executed. Commands can be separated by commas with optional spaces around them.118119Valid formats for ALLOW_COMMANDS or ALLOWED_COMMANDS:120121```bash122ALLOW_COMMANDS="ls,cat,echo" # Basic format123ALLOWED_COMMANDS="ls ,echo, cat" # With spaces (using alias)124ALLOW_COMMANDS="ls, cat , echo" # Multiple spaces125```126127### Request Format128129```python130# Basic command execution131{132 "command": ["ls", "-l", "/tmp"]133}134135# Command with stdin input136{137 "command": ["cat"],138 "stdin": "Hello, World!"139}140141# Command with timeout142{143 "command": ["long-running-process"],144 "timeout": 30 # Maximum execution time in seconds145}146147# Command with working directory and timeout148{149 "command": ["grep", "-r", "pattern"],150 "directory": "/path/to/search",151 "timeout": 60152}153```154155### Response Format156157Successful response:158159```json160{161 "stdout": "command output",162 "stderr": "",163 "status": 0,164 "execution_time": 0.123165}166```167168Error response:169170```json171{172 "error": "Command not allowed: rm",173 "status": 1,174 "stdout": "",175 "stderr": "Command not allowed: rm",176 "execution_time": 0177}178```179180## Security181182The server implements several security measures:1831841. **Command Whitelisting**: Only explicitly allowed commands can be executed1852. **Shell Operator Validation**: Commands after shell operators (;, &&, ||, |) are also validated against the whitelist1863. **No Shell Injection**: Commands are executed directly without shell interpretation187188## Development189190### Setting up Development Environment1911921. Clone the repository193194```bash195git clone https://github.com/yourusername/mcp-shell-server.git196cd mcp-shell-server197```1981992. Install dependencies including test requirements200201```bash202pip install -e ".[test]"203```204205### Running Tests206207```bash208pytest209```210211## API Reference212213### Request Arguments214215| Field | Type | Required | Description |216|-----------|------------|----------|-----------------------------------------------|217| command | string[] | Yes | Command and its arguments as array elements |218| stdin | string | No | Input to be passed to the command |219| directory | string | No | Working directory for command execution |220| timeout | integer | No | Maximum execution time in seconds |221222### Response Fields223224| Field | Type | Description |225|----------------|---------|---------------------------------------------|226| stdout | string | Standard output from the command |227| stderr | string | Standard error output from the command |228| status | integer | Exit status code |229| execution_time | float | Time taken to execute (in seconds) |230| error | string | Error message (only present if failed) |231232## Requirements233234* Python 3.11 or higher235* mcp>=1.1.0236237## License238239MIT License - See LICENSE file for details240
Full transparency — inspect the skill content before installing.