mcp-shell

The MCP Shell Server exposes a secure interface to execute whitelisted shell commands remotely using the MCP protocol. It validates commands against a predefined whitelist, supports input via stdin, and returns stdout, stderr, exit status, and execution time. This makes it suitable for controlled automation scenarios where you need to run specific shell operations from a client while preventing arbitrary command execution. To use it, configure your MCP client to connect to the server and pass a command array (e.g., ["ls", "-l"]) along with optional stdin, timeout, and directory fields. The server will only run commands that appear on the allowed list (as defined by ALLOW_COMMANDS) and will enforce safety checks around shell operators to avoid injection or unintended behavior.

Prerequisites:

• Python 3.11 or higher
• network access to install packages

Option 1: Install via Pip (recommended for most users)

pip install mcp-shell-server

Option 2: Install via Smithery (for automated client setups)

npx -y @smithery/cli install mcp-shell-server --client claude

After installation, configure the environment variable to restrict commands. Example:

export ALLOW_COMMANDS="ls,cat,pwd,grep,wc,touch,find"

Then start the server (see the specific command on your platform, typically via uvx as described in mcp_config).

Notes and tips:

• The server uses a whitelist to restrict executable commands. Update ALLOW_COMMANDS to include only the commands you want to permit.
• The server validates commands after shell operators to prevent unsafe executions; always rely on explicit whitelisting rather than relying on shell parsing.
• You can pass input through stdin when needed (stdin field in the request).
• If you encounter environment-related issues, ensure the ALLOW_COMMANDS string is properly formatted and that your client encodes the command array as required by the MCP client.
• For debugging, run the server locally and test with small commands before deploying to production.