Skip to main content
Glama
Sign In
enesjakoptzh
MCP Shell Server

MCP Shell Server

by diegofornalha
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

MCP Shell Server

codecov

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

Related MCP server: Shell MCP Server

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

Field

Type

Mandatory

Description

command

string[]

Yes

Command and its arguments as array elements

stdin

string

No

Input to be passed to the command

directory

string

No

Working directory for executing the command

timeout

whole

No

Maximum execution time in seconds

Response Fields

Field

Type

Description

stdout

string

Standard output of the command

stderr

string

Command error output

status

whole

Exit status code

execution_time

float

Time taken to execute (in seconds)

error

string

Error message (present only if failed)

Requirements

  • Python 3.11 or higher

  • mcp>=1.1.0

License

MIT License - See LICENSE file for details

Available Tools

1 tool
shell_executeC

Execute um comando shell Comandos permitidos:

Inputs: command (required), directory (required), stdin, timeout.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    C2.7/5.0

    Scored across 1 tool

    Disambiguation5/5

    With only one tool, there is no possibility for confusion or overlap between tools. The tool 'shell_execute' has a single, clearly defined purpose of executing shell commands, so disambiguation is perfect.

    Naming Consistency5/5

    Since there is only one tool, naming consistency is inherently perfect. The tool name 'shell_execute' follows a clear verb_noun pattern, but with no other tools to compare, it sets no pattern to deviate from.

    Tool Count2/5

    A single tool is too few for a server named 'MCP Shell Server', which implies broader shell-related functionality. While the tool covers basic command execution, the scope feels thin, lacking tools for tasks like listing files, checking processes, or managing environment variables that are typical in shell operations.

    Completeness2/5

    The tool set is severely incomplete for a shell server. It only provides execution, missing essential operations like file manipulation (e.g., read, write, delete), directory navigation, process management, or system information retrieval. This will likely cause agent failures when trying to perform common shell tasks beyond simple command execution.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers

    • mcp-shell-server

      tumf
      A
      license
      A
      quality
      A
      maintenance
      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
      201
      MIT

    • Shell MCP Server

      odysseus0
      A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that allows LLMs to execute shell commands and receive their output in a controlled manner.
      7
      MIT

    Appeared in Searches