Skip to main content
Glama
Sign In
enesjakozh

mcp-shell-server

by tumf
GitHub
Python
MIT License
74
  • Apple
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

Integrations

  • Code coverage reporting integration shown by the codecov badge in the README header, displaying test coverage metrics for the project.

MCP Shell Server

A secure shell command execution server implementing the Model Context Protocol (MCP). This server allows remote execution of whitelisted shell commands with support for stdin input.

Features

  • Secure Command Execution: Only whitelisted commands can be executed
  • Standard Input Support: Pass input to commands via stdin
  • Comprehensive Output: Returns stdout, stderr, exit status, and execution time
  • Shell Operator Safety: Validates commands after shell operators (; , &&, ||, |)
  • Timeout Control: Set maximum execution time for commands

MCP client setting in your Claude.app

Published version

code ~/Library/Application\ Support/Claude/claude_desktop_config.json
{ "mcpServers": { "shell": { "command": "uvx", "args": [ "mcp-shell-server" ], "env": { "ALLOW_COMMANDS": "ls,cat,pwd,grep,wc,touch,find" } }, } }

Local version

Configuration
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
{ "mcpServers": { "shell": { "command": "uv", "args": [ "--directory", ".", "run", "mcp-shell-server" ], "env": { "ALLOW_COMMANDS": "ls,cat,pwd,grep,wc,touch,find" } }, } }
Installation

Installing via Smithery

To install Shell Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install mcp-shell-server --client claude

Manual Installation

pip install mcp-shell-server

Installing via Smithery

To install Shell Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install mcp-shell-server --client claude

Usage

Starting the Server

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

The ALLOW_COMMANDS (or its alias ALLOWED_COMMANDS ) environment variable specifies which commands are allowed to be executed. Commands can be separated by commas with optional spaces around them.

Valid formats for ALLOW_COMMANDS or ALLOWED_COMMANDS:

ALLOW_COMMANDS="ls,cat,echo" # Basic format ALLOWED_COMMANDS="ls ,echo, cat" # With spaces (using alias) ALLOW_COMMANDS="ls, cat , echo" # Multiple spaces

Request Format

# Basic command execution { "command": ["ls", "-l", "/tmp"] } # Command with stdin input { "command": ["cat"], "stdin": "Hello, World!" } # Command with timeout { "command": ["long-running-process"], "timeout": 30 # Maximum execution time in seconds } # Command with working directory and timeout { "command": ["grep", "-r", "pattern"], "directory": "/path/to/search", "timeout": 60 }

Response Format

Successful response:

{ "stdout": "command output", "stderr": "", "status": 0, "execution_time": 0.123 }

Error response:

{ "error": "Command not allowed: rm", "status": 1, "stdout": "", "stderr": "Command not allowed: rm", "execution_time": 0 }

Security

The server implements several security measures:

  1. Command Whitelisting: Only explicitly allowed commands can be executed
  2. Shell Operator Validation: Commands after shell operators (;, &&, ||, |) are also validated against the whitelist
  3. No Shell Injection: Commands are executed directly without shell interpretation

Development

Setting up Development Environment

  1. Clone the repository
git clone https://github.com/yourusername/mcp-shell-server.git cd mcp-shell-server
  1. Install dependencies including test requirements
pip install -e ".[test]"

Running Tests

pytest

API Reference

Request Arguments

FieldTypeRequiredDescription
commandstring[]YesCommand and its arguments as array elements
stdinstringNoInput to be passed to the command
directorystringNoWorking directory for command execution
timeoutintegerNoMaximum execution time in seconds

Response Fields

FieldTypeDescription
stdoutstringStandard output from the command
stderrstringStandard error output from the command
statusintegerExit status code
execution_timefloatTime taken to execute (in seconds)
errorstringError message (only present if failed)

Requirements

  • Python 3.11 or higher
  • mcp>=1.1.0

License

MIT License - See LICENSE file for details

You must be authenticated.

A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

Tools

A secure shell command execution server implementing the Model Context Protocol (MCP). This server allows remote execution of whitelisted shell commands with support for stdin input.

  1. Features
    1. MCP client setting in your Claude.app
      1. Published version
      2. Local version
      3. Installing via Smithery
      4. Manual Installation
      5. Installing via Smithery
    2. Usage
      1. Starting the Server
      2. Request Format
      3. Response Format
    3. Security
      1. Development
        1. Setting up Development Environment
        2. Running Tests
      2. API Reference
        1. Request Arguments
        2. Response Fields
      3. Requirements
        1. License

          Related Resources

          Related MCP Servers

          • Shell-MCP

            kevinwatt
            A
            security
            A
            license
            A
            quality
            A secure MCP server for executing whitelisted shell commands with resource and timeout controls, designed for integration with Claude and other MCP-compatible LLMs.
            Last updated -
            20
            143
            2
            TypeScript
            MIT License

          • Windows CLI MCP Server

            SimonB97
            A
            security
            A
            license
            A
            quality
            A Model Context Protocol server that provides secure command-line access to Windows systems, allowing MCP clients like Claude Desktop to safely execute commands in PowerShell, CMD, and Git Bash shells with configurable security controls.
            Last updated -
            9
            350
            105
            JavaScript
            MIT License

          • MCP Terminal Server

            RinardNick
            A
            security
            A
            license
            A
            quality
            A secure terminal execution server that enables controlled command execution with security features and resource limits via the Model Context Protocol (MCP).
            Last updated -
            1
            12
            1
            JavaScript
            MIT License
            • Apple

          • Super Shell MCP Server

            cfdude
            -
            security
            A
            license
            -
            quality
            An MCP server that enables secure execution of shell commands across Windows, macOS, and Linux with built-in whitelisting and approval mechanisms for enhanced security.
            Last updated -
            13
            JavaScript
            MIT License
            • Linux
            • Apple

          View all related MCP servers

          Appeared in Searches

          New MCP Servers

          ID: rt2d4pbn22