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

Request Format

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

Response Format

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

pip install -e ".[test]"

Running Tests

pytest

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

Install Server

HTTP connection URL

security – no known vulnerabilities

license - not found

quality - confirmed to work

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Tools

shell_execute

A secure server that implements the Model Context Protocol (MCP) to enable controlled execution of authorized shell commands with stdin support.

Related MCP Servers

mcp-shell-server
tumf
A
security
A
license
A
quality
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.
Last updated -
1
116
Python
MIT License
Windows CLI MCP Server
SimonB97
A
security
A
license
A
quality
A Model Context Protocol server that provides secure command-line access to Windows systems, allowing MCP clients like Claude Desktop to safely execute commands in PowerShell, CMD, and Git Bash shells with configurable security controls.
Last updated -
9
700
231
JavaScript
MIT License
MCP Terminal Server
RinardNick
A
security
A
license
A
quality
A secure terminal execution server that enables controlled command execution with security features and resource limits via the Model Context Protocol (MCP).
Last updated -
1
418
6
JavaScript
MIT License
Super Shell MCP Server
cfdude
A
security
A
license
A
quality
An MCP server that enables secure execution of shell commands across Windows, macOS, and Linux with built-in whitelisting and approval mechanisms for enhanced security.
Last updated -
9
433
6
JavaScript
MIT License

View all related MCP servers

MCP Shell Server

MCP Shell Server

Features

Configuring the MCP client in your Claude.app

Published version

Local version

Settings

Installation

Use

Starting the Server

Request Format

Response Format

Security

Development

Setting Up the Development Environment

Running Tests

API Reference

Request Arguments

Response Fields

Requirements

License

Tools

Related MCP Servers

mcp-shell-server

Windows CLI MCP Server

MCP Terminal Server

Super Shell MCP Server

New MCP Servers

MCP directory API