Shell

Provides secure shell command execution for AI apps via MCP, with directory isolation, multiple shells, and timeouts.

python

GitHub Stars

python

Language

7 months ago

First Indexed

3 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "mcp-mirror-blazickjp_shell-mcp-server": {
      "command": "uv",
      "args": [
        "run",
        "shell-mcp-server",
        "/path/to/allowed/dir1",
        "/path/to/allowed/dir2",
        "--shell",
        "bash",
        "/bin/bash",
        "--shell",
        "zsh",
        "/bin/zsh"
      ],
      "env": {
        "COMMAND_TIMEOUT": "30"
      }
    }
  }
}

You can securely execute shell commands from your AI applications using this Shell MCP Server. It lets you run commands in restricted directories, supports multiple shells, and enforces timeouts to keep systems safe while integrating with the Model Context Protocol.

How to use

You connect an MCP client to the Shell MCP Server to send shell commands for execution. The server restricts where commands can run, limiting them to pre-approved directories and shells. It supports bash, sh, cmd, and powershell, and it will automatically stop any command that exceeds its time limit. Use it to automate tasks, check system status, or perform project operations from within a controlled environment.

How to install

Prerequisites: You need Python installed on your system. Install Python from the official sources if it is not already available.

Option 1: Install with pip. Run this command in your terminal.

pip install shell-mcp-server

Option 2: Install with uv (recommended in many setups). Run this command in your terminal.

uv pip install shell-mcp-server

After installation, you start the server using an explicit stdio approach. The server runs locally and is configured to allow execution only in approved directories with specified shells.

Configuration and usage notes

Configure the server to limit execution to allowed directories and shells. For a practical setup, you specify the allowed directories and the shells you enable, then start the server so clients can send commands within those constraints.

Environment variable support: You can set a timeout for command execution. The default timeout is 30 seconds if you do not provide a value.

Example configuration for local startup

{
  "type": "stdio",
  "name": "shell_mcp",
  "command": "uv",
  "args": [
    "run",
    "shell-mcp-server",
    "/path/to/allowed/dir1",
    "/path/to/allowed/dir2",
    "--shell", "bash", "/bin/bash",
    "--shell", "zsh", "/bin/zsh"
  ]
}

Security and safety considerations

Directory isolation ensures commands execute only in predefined locations. Only configured shells are permitted, and each command runs with the same permissions as the server process, reducing the risk of elevation. A configurable timeout protects against long-running or hanging processes.

Troubleshooting

If a command is not executing, verify that the requested directory is included in the allowed list and that the selected shell is among the configured options. Check that the timeout value is appropriate for the workload and that the MCP client is sending valid commands within the allowed scope.

Notes

This server is designed to work across Unix and Windows systems and is safe by default with built-in directory and shell validation.

Available tools

execute_command

Function to run a shell command within the allowed directories and shells, with an enforced timeout and directory validation.

Built by

VeilStrat

AI signals for GTM teams