home / mcp / shell mcp server

Shell MCP Server

Provides a secure MCP shell execution server with stdin support and comprehensive command results.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "diegofornalha-mcp-shell-server": {
      "command": "uvx",
      "args": [
        "mcp-shell-server"
      ],
      "env": {
        "ALLOW_COMMANDS": "ls,cat,echo",
        "ALLOWED_COMMANDS": "ls,cat,echo"
      }
    }
  }
}

You can run authorized shell commands remotely with the MCP Shell Server. It validates commands against a whitelist, supports input via stdin, and returns stdout, stderr, exit status, and execution time for each request, enabling safe remote automation and debugging workflows.

How to use

To run commands against the MCP Shell Server, you configure a client to target the server and send a request that includes the command and any optional parameters. You can provide input through stdin, set a working directory, and specify a maximum allowed execution time. The server ensures only whitelisted commands are executed and returns the command output along with timing information.

Typical usage patterns include:

Run a single command and capture its output: send the command as a list of arguments and do not rely on shell features.
Pass input to a command via stdin when the command reads from standard input, for example providing data to a program that waits for input.
Limit execution time to prevent hangs by setting a timeout for long-running processes.
Rely on the white list of allowed commands to maintain security; each request is checked against this allow list.

How to install

Prerequisites you need before installing: Python 3.11 or newer.

pip install mcp-shell-server

Start the server using the command line with a defined set of allowed commands. For example, you can restrict to a small set for safety.

ALLOW_COMMANDS="ls,cat,echo" uvx mcp-shell-server
```

# Or using the alias form
ALLOWED_COMMANDS="ls,cat,echo" uvx mcp-shell-server

Additional notes

If you choose a local start, you can also run the server with a slightly different command while keeping the same allowed commands.

ALLOWED_COMMANDS="ls,cat,echo" uvx mcp-shell-server

Security and usage details

Security is enforced through a whitelist of allowed commands and validation of shell operators. Commands are executed directly without a shell interpreter to minimize injection risks.

Configuration example for a client

To configure a client that talks to the MCP Shell Server, you typically specify the server command and the list of allowed commands in your environment or startup script.

Available tools

execute_command

Executes a whitelisted command with given arguments and returns stdout, stderr, exit status, and execution time.

stdin_support

Passes input to the command via stdin when provided.

timeout_control

Limits the maximum execution time to prevent long-running processes.

operator_validation

Validates commands following shell operators to ensure they are whitelisted.

whitelist_enforcement

Maintains and enforces a whitelist of allowed commands for every request.