home / mcp / shell mcp server

Shell MCP Server

Secure shell command execution MCP server for Claude AI. Enables controlled shell access within specified directories.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "blazickjp-shell-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/shell-mcp-server",
        "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 deploy the Shell MCP Server to give your AI applications secure, configurable shell access. It lets you run trusted commands in controlled directories, through multiple shells, with automatic timeouts and strong safety checks, all under the Model Context Protocol.

How to use

You interact with the server through an MCP client. Install the server, run it in a supported environment, and point your client at the configured MCP endpoint. You can execute shell commands in approved directories, select a preferred shell (bash, sh, cmd, or powershell), and rely on automatic timeouts to prevent long-running tasks. Use this to automate file operations, project management tasks, or system information gathering within strict safety boundaries.

To use with a local, self-hosted server, you typically run the MCP server locally and connect to it from your client. Commands are executed in whitelisted directories, with the working directory and shell validated before each run. This ensures your automation can perform necessary tasks without risking access to sensitive areas or unauthorized shells.

How to install

Prerequisites you need before installing include Python and a package manager your system uses. Ensure you have Python installed and available on your PATH.

Install the Shell MCP Server with your preferred method. You can install via Python’s package manager and then use a runner to start the server.

pip install shell-mcp-server

If you prefer using the UV runner for faster startup and isolated environments, install via the UV-based workflow and then run the server accordingly.

uv pip install shell-mcp-server

Configuration and usage notes

Configure the server to restrict commands to allowed directories and shells. You can specify the directories that commands are allowed to run in, and list the shells that can be used. The server also supports a timeout to automatically terminate long-running commands and prevent resource abuse.

Environment variable you may configure to control maximum command runtime: COMMAND_TIMEOUT. Set it to the number of seconds you want as the limit (default is 30 seconds if not set).

Security highlights

Directory isolation ensures commands run only in approved locations. Shell control restricts usage to pre-approved shells. Timeouts protect against runaway processes. Path validation prevents directory traversal attacks. Commands execute with the same permissions as the server process, reducing the risk of privilege escalation.

Available tools

secure_execution

Ensures commands run only within specified directories and under configured shells, with enforced isolation.

multi_shells

Supports multiple shells (bash, sh, cmd, powershell) for command execution.

timeout_control

Imposes a configurable timeout to automatically terminate long-running commands.

cross_platform

Operates on Unix and Windows systems with consistent behavior.

safe_by_default

Built-in validation of directories and shells to provide safe defaults.