Shell

You can securely execute whitelisted shell commands on a remote server, with stdin support, stdout/stderr collection, and execution timing. This MCP server enforces a whitelist to prevent unsafe actions and provides controlled, audited command execution for automation and remote tooling.

How to use

You connect to the MCP server from your client and request command executions by sending a command array. The server will run only whitelisted commands, pass any provided input through stdin, and return stdout, stderr, the exit status, and the total execution time. If a command would violate the whitelist or shell operator safety rules, you receive a clear error with the explanation and no output is produced.

Practical usage patterns include running quick inspection commands like listing files or displaying current directories, performing searches, or editing files via standard tools, all while staying within the allowed set of commands. If you need to perform longer computations, you can set a timeout so the server terminates the command after the specified duration. When you provide a working directory, the server executes the command inside that directory. If you supply input data, it is passed to the command via stdin.

How to install

# Prerequisites
- Python 3.11 or higher
- pip available in your environment

# Install the MCP server package
pip install mcp-shell-server

# Start the server locally (example command)
ALLOW_COMMANDS="ls,cat,echo" uvx mcp-shell-server
# Or using the alias for the same purposes
ALLOWED_COMMANDS="ls,cat,echo" uvx mcp-shell-server

Additional sections

Security is built into the server to prevent unauthorized actions. It uses a command whitelist to restrict executable commands, validates commands following shell operators (;, &&, ||, |) against the same whitelist, and executes commands without shell interpretation to avoid injection risks.

Configuration and operational notes: you control which commands are allowed by setting environment variables when you start the server. The server can be run via standard input/output (stdio) with a direct runtime command or via an alternative launcher, depending on how you deploy it.

If you need to validate behavior or reproduce issues, capture stdout and stderr from each request and compare them against the expected outcomes. Use a timeout to bound execution time, and ensure the provided directory exists and is accessible by the server process.

Troubleshooting tips: ensure the command whitelist is correctly configured and that the server process has the necessary permissions to access the requested directories. If a request returns a generic error, check whether the command is present in the whitelist and verify the exact arguments passed to the command.

Available tools

secure_command_execution

Executes only whitelisted commands, preventing execution of disallowed commands and avoiding shell injection by running commands directly without shell interpretation.

stdin_support

Allows input data to be sent to the running command via stdin for interactive or data-driven executions.

output_capture

Returns stdout, stderr, exit status, and execution time for each command execution.

shell_operator_validation

Validates commands that appear after shell operators to ensure they are still within the whitelist.

timeout_control

Supports a timeout to terminate long-running commands after a specified duration.