tumf/mcp-shell-server

完整文档

{
  "mcpServers": {
    "shell": {
      "command": "uvx",
      "args": [
        "mcp-shell-server"
      ],
      "env": {
        "ALLOW_COMMANDS": "ls,cat,pwd,grep,wc,touch,find"
      }
    },
  }
}

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"
      }
    },
  }
}

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

pip install mcp-shell-server

ALLOW_COMMANDS 或 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

ALLOW_PATTERNS="python[0-9.]*,node"    # Command-name patterns only

这种加固是尽力而为的深度防御，而非针对任意不可信命令执行的完整沙箱。对于不可信的客户端或宽泛的命令白名单，请将服务器运行在具有最小权限文件系统和网络访问权限的 OS/容器沙箱中。

子进程环境

命令在隔离的子环境中运行。服务器不会将完整的父进程环境传递给子命令，因此 API 令牌、凭据和 SECRET_TOKEN 等无关变量默认均不存在。默认情况下，子环境仅包含命令执行所需的最小启动键：POSIX 系统上的 PATH，以及适用时的 Windows 进程启动键（COMSPEC、PATHEXT、SYSTEMROOT 和 WINDIR）。

使用 MCP_SHELL_CHILD_ENV_ALLOWLIST 来显式允许从父进程继承或从单条命令的环境覆盖中接受额外的环境变量名称。该白名单以逗号分隔，并使用精确的环境变量名称：

MCP_SHELL_CHILD_ENV_ALLOWLIST="LANG,LC_ALL,MY_TOOL_HOME" \
ALLOW_COMMANDS="printenv,my-tool" \
uvx mcp-shell-server

结构化审计日志

每次命令调用都会发出一个名为 shell_execution_audit 的 mcp-shell-server.audit 日志事件。审计记录涵盖：执行成功、子进程创建前的验证拒绝、超时、输出上限终止，以及包括子进程创建失败在内的进程错误。

审计元数据包括：

• timestamp、duration 和 result_type

• 命令名称和脱敏后的 argv

• 解析后的工作 directory

• stdin/stdout/stdout append 的重定向标志

• 提供的脱敏单次调用环境覆盖元数据

• 生效的 timeout 和 output_limit

• stdout_bytes 和 stderr_bytes

• 可用的 return_code

• 适用的 rejection_reason 或 error_type

审计日志特意不包含原始的 stdout 或 stderr 正文。包含 SECRET、TOKEN、PASSWORD、PASSWD、API_KEY、ACCESS_KEY、PRIVATE_KEY、KEY、CREDENTIAL 或 AUTH 等标记的类密钥 argv 和环境名称或值会被替换为 [REDACTED]。较长的非数字值将由简短的 SHA-256 摘要代替原始值。

请求格式directory 参数是可选的。如果省略，命令将在 MCP 服务器进程的当前工作目录（server process CWD）中运行。相对 directory 值将基于该服务器进程 CWD 进行解析。此基准目录不是 MCP 客户端的 CWD，而是启动 mcp-shell-server 的进程的工作目录。

python

# Basic command execution in the server process CWD