MCP Shell Server
A secure server for executing shell commands that implements the Model Context Protocol (MCP). This server allows remote execution of authorized shell commands with support for input via stdin.
Features
- Secure Command Execution : Only authorized commands can be executed
- Standard Input Support : Passes input to commands via stdin
- Comprehensive Output : Returns stdout, stderr, exit code and execution time
- Security with Shell Operators : Validates commands after shell operators (;, &&, ||, |)
- Timeout Control : Sets maximum execution time for commands
Configuring the MCP client in your Claude.app
Published version
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"shell": {
"command": "uvx",
"args": [
"mcp-shell-server"
],
"env": {
"ALLOW_COMMANDS": "ls,cat,pwd,grep,wc,touch,find"
}
},
}
}
Local version
Settings
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"shell": {
"command": "uv",
"args": [
"--directory",
".",
"run",
"mcp-shell-server"
],
"env": {
"ALLOW_COMMANDS": "ls,cat,pwd,grep,wc,touch,find"
}
},
}
}
Installation
pip install mcp-shell-server
Use
Starting the Server
ALLOW_COMMANDS="ls,cat,echo" uvx mcp-shell-server
# Ou usando o alias
ALLOWED_COMMANDS="ls,cat,echo" uvx mcp-shell-server
The ALLOW_COMMANDS environment variable (or its alias ALLOWED_COMMANDS ) specifies which commands can be executed. Commands can be separated by commas with optional spaces around them.
Valid formats for ALLOW_COMMANDS or ALLOWED_COMMANDS:
ALLOW_COMMANDS="ls,cat,echo" # Formato básico
ALLOWED_COMMANDS="ls ,echo, cat" # Com espaços (usando alias)
ALLOW_COMMANDS="ls, cat , echo" # Múltiplos espaços
# Execução básica de comando
{
"command": ["ls", "-l", "/tmp"]
}
# Comando com entrada stdin
{
"command": ["cat"],
"stdin": "Hello, World!"
}
# Comando com timeout
{
"command": ["long-running-process"],
"timeout": 30 # Tempo máximo de execução em segundos
}
# Comando com diretório de trabalho e timeout
{
"command": ["grep", "-r", "pattern"],
"directory": "/path/to/search",
"timeout": 60
}
Successful response:
{
"stdout": "saída do comando",
"stderr": "",
"status": 0,
"execution_time": 0.123
}
Error response:
{
"error": "Comando não permitido: rm",
"status": 1,
"stdout": "",
"stderr": "Comando não permitido: rm",
"execution_time": 0
}
Security
The server implements several security measures:
- Command Whitelist : Only explicitly allowed commands can be executed
- Shell Operator Validation : Commands after shell operators (;, &&, ||, |) are also validated against the whitelist
- No Shell Injection : Commands are executed directly without shell interpretation
Development
Setting Up the Development Environment
- Clone the repository
git clone https://github.com/yourusername/mcp-shell-server.git
cd mcp-shell-server
- Install dependencies including test requirements
Running Tests
API Reference
Request Arguments
| Field | Type | Mandatory | Description |
|---|
| command | string[] | Yes | Command and its arguments as array elements |
| stdin | string | No | Input to be passed to the command |
| directory | string | No | Working directory for executing the command |
| timeout | whole | No | Maximum execution time in seconds |
Response Fields
| Field | Type | Description |
|---|
| stdout | string | Standard output of the command |
| stderr | string | Command error output |
| status | whole | Exit status code |
| execution_time | float | Time taken to execute (in seconds) |
| error | string | Error message (present only if failed) |
Requirements
- Python 3.11 or higher
- mcp>=1.1.0
License
MIT License - See LICENSE file for details