The Shell MCP Server provides secure, sandboxed execution of shell commands for AI applications. It restricts command execution to pre-approved directories and a set of allowed shells (bash, sh, cmd, powershell), with a configurable timeout to prevent long-running processes. To use it, install the server (via pip or uv) and run it under uv as shown in the Quick Start example. The server exposes an interface that your AI tool can call with a command, a chosen shell, and a working directory. Examples in the repository show common workflows such as listing directory contents, searching files, and performing project management tasks, all while honoring directory isolation and per-command timeouts. You can integrate this MCP server with Claude Desktop or other clients by pointing them to the configured mcpServers entry, including the command (uv) and arguments to launch the server with the allowed directories and shells.

Prerequisites:

• Python 3.11 or newer
• Internet access to install packages

Installation steps:

1. Create and activate a virtual environment (optional but recommended):

   Python-based setup

   python -m venv .venv source .venv/bin/activate # on Unix or macOS .venv\Scripts\activate.bat # on Windows

2. Install the Shell MCP Server (Python package):

   Using pip (Python package manager)

   pip install shell-mcp-server

3. Alternatively, install and run using uv (recommended): uv pip install shell-mcp-server

4. Verify installation by listing installed package or running a test command as documented by the project.

5. Create your mcp_config (see JSON example) and start the server with the appropriate command and environment variables.

Tips and considerations:

• Ensure the directories you allow for command execution are correct and secure.
• Use the COMMAND_TIMEOUT environment variable to limit execution time per command (default is 30 seconds).
• If you update allowed shells, keep the paths to the shell executables accurate (e.g., /bin/bash, /bin/zsh).
• For Claude Desktop integration, follow the provided example to add your mcpServer entry to Claude’s config, adjusting directory and shell paths as needed.
• If you encounter permission or path validation errors, verify that the server process has access to the configured directories and that the shell paths exist on the target system.
• Development and testing can be performed in a virtual environment to avoid system-wide changes.