MCP Shell Server

MCP Shell Server

A secure server for executing shell commands that implements the Model Context Protocol (MCP). This server allows remote execution of authorized shell commands with support for input via stdin.

Features

  • Secure Command Execution : Only authorized commands can be executed
  • Standard Input Support : Passes input to commands via stdin
  • Comprehensive Output : Returns stdout, stderr, exit code and execution time
  • Security with Shell Operators : Validates commands after shell operators (;, &&, ||, |)
  • Timeout Control : Sets maximum execution time for commands

Configuring the MCP client 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

Settings
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
pip install mcp-shell-server

Use

Starting the Server

ALLOW_COMMANDS="ls,cat,echo" uvx mcp-shell-server # Ou usando o alias ALLOWED_COMMANDS="ls,cat,echo" uvx mcp-shell-server

The ALLOW_COMMANDS environment variable (or its alias ALLOWED_COMMANDS ) specifies which commands can 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" # Formato básico ALLOWED_COMMANDS="ls ,echo, cat" # Com espaços (usando alias) ALLOW_COMMANDS="ls, cat , echo" # Múltiplos espaços

Request Format

# Execução básica de comando { "command": ["ls", "-l", "/tmp"] } # Comando com entrada stdin { "command": ["cat"], "stdin": "Hello, World!" } # Comando com timeout { "command": ["long-running-process"], "timeout": 30 # Tempo máximo de execução em segundos } # Comando com diretório de trabalho e timeout { "command": ["grep", "-r", "pattern"], "directory": "/path/to/search", "timeout": 60 }

Response Format

Successful response:

{ "stdout": "saída do comando", "stderr": "", "status": 0, "execution_time": 0.123 }

Error response:

{ "error": "Comando não permitido: rm", "status": 1, "stdout": "", "stderr": "Comando não permitido: rm", "execution_time": 0 }

Security

The server implements several security measures:

  1. Command Whitelist : 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 the 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

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

Response Fields

FieldTypeDescription
stdoutstringStandard output of the command
stderrstringCommand error output
statuswholeExit status code
execution_timefloatTime taken to execute (in seconds)
errorstringError message (present only if failed)

Requirements

  • Python 3.11 or higher
  • mcp>=1.1.0

License

MIT License - See LICENSE file for details

-
security - not tested
-
license - not tested
-
quality - not tested

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

A secure server that implements the Model Context Protocol (MCP) to enable controlled execution of authorized shell commands with stdin support.

  1. Features
    1. Configuring the MCP client in your Claude.app
      1. Published version
      2. Local version
    2. Use
      1. Starting the Server
      2. Request Format
      3. Response Format
    3. Security
      1. Development
        1. Setting Up the Development Environment
        2. Running Tests
      2. API Reference
        1. Request Arguments
        2. Response Fields
      3. Requirements
        1. License

          Related MCP Servers

          • A
            security
            A
            license
            A
            quality
            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.
            Last updated -
            1
            74
            Python
            MIT License
            • Apple
          • 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
          • A
            security
            F
            license
            A
            quality
            A Model Context Protocol server implementation that enables secure remote command execution via SSH, with features for managing and using SSH credentials.
            Last updated -
            5
            3
            JavaScript
          • -
            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

          ID: sx9bf448k1