MCP Shell Server

MCP Shell 服务

一个实现 Model Context Protocol（MCP）的可信执行服务。它会以 argv 数组的形式运行允许列表中的命令，并支持 stdin 输入、受控重定向、精简的子进程环境、执行限制和结构化审计日志。

此软件包不是沙盒。 允许某个命令运行，就意味着将服务进程现有的操作系统权限交给该程序。配置前请阅读可信执行约定。

功能

• 基于 argv 的命令执行：通过子进程 argv 运行允许的命令，不进行 shell 字符串解释
• 标准输入支持：通过 stdin 向命令传递输入
• 完整输出：返回 stdout、stderr、退出状态和执行时间
• 安全的管道支持：管道会保留并验证 argv 片段，而不是调用 shell
• 执行限制：强制执行服务端默认超时、最大超时和输出字节数上限
• 受控重定向：<、> 和 >> 的目标必须位于所请求的工作目录内
• 精简的子进程环境：子进程接收的是精简的允许列表环境，而不是继承服务端的所有机密信息
• 结构化审计日志：成功、拒绝、超时、输出上限和进程错误等结果都会在脱敏后记录

可信执行约定

请在阅读下方的配置示例前先阅读本节。服务启动时会通过日志记录器（stderr）发出相同的警告一次；MCP stdout 帧格式不变。

服务控制的内容

mcp-shell-server 会对自身行为实施边界控制：

• 它直接启动哪些可执行文件名称（ALLOW_COMMANDS、ALLOW_PATTERNS），
• 基于 argv 创建进程，不进行 shell 字符串解释，
• 服务管理的 <、> 和 >> 重定向限制在所请求的工作目录内，
• 它构建的子进程环境，
• 超时和输出字节数限制，
• 结构化审计记录。

服务无法控制的内容

允许某个命令运行，就意味着授权该程序使用服务进程现有的操作系统身份、文件系统访问权限、网络访问权限和凭据。ALLOW_COMMANDS 和 ALLOW_PATTERNS 只限制服务直接启动的命令名称。它们不能保证以下行为受到限制：

• 允许的程序所启动的子进程，
• 程序专用的解释器、表达式语言或插件，
• 程序自行读取的配置文件、点文件或由环境驱动的行为，
• 程序自行执行的文件系统读写（服务管理的重定向除外），
• 程序自行执行的网络访问。

安全性部分所述的命令专属拒绝规则，是针对已知危险参数形式的尽力纵深防御。这些规则并不详尽，也不能证明允许的程序是安全的。

不可信输入需要外部隔离

受信任且经过身份验证的 MCP 客户端，并不意味着它处理的内容也值得信任。模型提供的文本、获取的网页、问题文本和代码仓库内容都是不可信输入，即使客户端本身值得信任也是如此，而且 LLM 可能会被诱导，根据这些内容构造请求。

如果任何请求或服务器能够访问的任何文件可能源自不可信输入，请在由外部独立强制执行的 OS 边界（容器、VM、jail 或 OS 策略）内运行服务器，并确保该边界提供：

• 最小权限身份 — 使用专用的非 root 用户，且该用户在主机上没有管理权限。
• 文件系统范围 — 仅挂载工作负载所需的目录，并尽可能设为只读；主机配置、SSH 密钥和云凭据文件应不可访问。
• 网络限制 — 默认拒绝出站流量，只允许工作负载所需的目标地址。
• 排除凭据 — 服务器进程无法访问任何环境令牌、云实例元数据或 Agent 套接字。
• 后代进程约束 — 使用进程/cgroup 命名空间，使允许的程序所启动的进程受到限制，并在沙箱销毁时一并回收。
• 资源限制 — 在此软件包之外强制执行 CPU、内存、磁盘、进程数和运行时限额。

应根据工作负载的需要尽量缩小允许列表；缩小允许列表可以降低风险，但绝不能替代上述边界。

Claude.app 中的 MCP 客户端设置

已发布版本

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

本地版本

配置

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

安装

通过 Smithery 安装

要通过 Smithery 自动为 Claude Desktop 安装 Shell Server：

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

手动安装

pip install mcp-shell-server

用法

启动服务

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

ALLOW_COMMANDS（或其别名 ALLOWED_COMMANDS）环境变量用于指定允许执行的命令。命令之间可以用逗号分隔，逗号两侧可以有空格。

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 可用于指定以逗号分隔的正则表达式，用来匹配命令名称。每个模式都采用完全匹配语义，因此 ALLOW_PATTERNS="ls" 只允许命令名称 ls，不允许 lsof 或 ls -la。包含空格或 shell 元字符的模式和命令名称会被拒绝；不要使用 ALLOW_PATTERNS 来描述 shell 命令字符串或参数级策略。

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

允许某个命令名称，并不意味着该程序自身基于参数的执行功能已受到沙箱保护。即使二进制文件已获允许，服务端仍会默认强化参数安全：已知可执行其他程序的参数组合（例如 find -exec/-execdir/-ok/-okdir、shell/解释器启动器和 JS 运行时（例如 deno/bun）、awk system()、tar 外部程序选项（例如 tar --checkpoint-action=exec，所有 checkpoint 操作都会被拒绝）、env、xargs、命令包装工具（例如 timeout/nice/nohup/setarch/strace/valgrind）、shell 转义工具（例如 sed/less/vim/ssh）、常见的其他名称（例如 gfind/gawk/gtar/bsdtar/gsort）、GNU sort 中用于指定外部程序、输出路径、外部文件列表或外部临时目录的选项（--compress-program、-o/--output、--files0-from 和 -T/--temporary-directory，包括缩写和组合形式，例如 --co、--o、-ro FILE 和 -rT DIR）、所有 Git 命令级配置覆盖项、持久化的 git config 写入，以及下文所述的 Git 子命令执行选项）都会在创建子进程前被拒绝。例如，ALLOW_COMMANDS="git" 并不允许执行 git -c user.name=Example status、git -c alias.pwn=!sh -c "touch marker" pwn 或 git config alias.pwn '!sh -c "touch marker"'；无论键或值是什么，所有全局 git -c <name=value> 和 git -c<name=value> 覆盖项都会被拒绝。诸如 setarch、strace、valgrind、deno 和 bun 等危险名称一律会被拒绝，包括仅查看版本或仅附加到进程的形式，例如 deno --version 或 strace -p PID；允许列表中的条目也无法覆盖此规则。 Git 子命令的执行选项会根据有限的 Git 2.53.0 选项语法予以拒绝：git grep 的分页器选择（-O，包括附加和组合形式，例如 -OP、-nOP、-1OP，以及带任意非空前缀的 --open-files-in-pager，例如 --op）；git rebase 的执行选项（-x，包括附加和组合形式，例如 -xP、-qxP，以及带任意非空前缀的 --exec，例如 --ex，包括出现在操作数之后的情况）；所有 git filter-branch 调用；以及 run 紧接在 bisect 后面的 git bisect run。对于其他所有子命令，--exec 及其非空前缀（--e、--ex、--exe）仍会作为远程助手选择器遭到拒绝（例如 git push --exec=PROG）。由全局选项（-C、--git-dir、--work-tree、--namespace，……）以及需要取值的 grep/rebase 选项（-e、-f、--context、--onto、-s、-X、--strategy-option，……）所消耗的值属于数据，不会再次扫描，因此允许 git grep -e -O data 和 git rebase --onto --exec；未被消耗的 -- 或 --end-of-options 会结束 grep/rebase 选项解析，而 grep 也会在遇到第一个操作数时停止，(/) 除外。包含目标选项的未知短选项字母和有歧义的前缀（例如 git grep --o=P）会被保守地拒绝。git send-email 的程序选择器会通过有限的 Git 2.53.0 识别器予以拒绝；该识别器会按顺序对剩余参数执行三轮 Getopt::Long 解析（身份、帮助/别名列表，然后是主选项），并同时考虑默认排列模式和 POSIXLY_CORRECT 要求的顺序模式；在任一解析方式下可到达的选择器都会被拒绝：选中 --sendmail-cmd、--to-cmd、--cc-cmd 和 --header-cmd 时一律拒绝，包括值为空或缺失，以及使用 --dry-run、后续覆盖选项或 --no-header-cmd 的情况；当 --smtp-server 的值缺失、为空、以 / 或 \ 开头，或以 ASCII 字母和冒号开头（例如 C:）时，会予以拒绝。该路径规则是对 POSIX 和 Windows 路径写法的保守并集，因此也可能拒绝 Git 实际不会运行的驱动器相对路径或根路径字符串；这并不表示 Windows 运行时隔离。选项名称不区分大小写，可使用 --、- 或 + 前缀，也可使用唯一缩写，例如 --sendm；精确名称（例如 --smtp-server-port 和 --smtp-server-option）优先，而包含选择器的有歧义前缀（例如 --send、--cc-c、--to-c 或 --smtp-serv）会被保守地拒绝，并非因为它们在 Git 中都会运行程序。普通 SMTP 主机（--smtp-server=smtp.example.invalid、localhost、127.0.0.1、[::1]）、-h、--dump-aliases、--dry-run、由需要取值的选项消耗的值（git send-email --subject --sendmail-cmd=DATA、--identity --sendmail-cmd=DATA），以及未被消耗的 -- 之后的参数，仍然允许。操作数之后仍会识别选项；--end-of-options 不会结束 send-email 选项解析；被当作必需值消耗的 -- 则属于数据。早期解析阶段中的无效词元（带等号附加值的标志、空的必需字符串或无效数值）仍会保留在 argv 中。两种模式的并集可能会拒绝只在一种模式下会被消耗的、看起来像选择器的数据。配置驱动的助手（sendemail.sendmailCmd、sendemail.smtpServer、sendemail.toCmd、sendemail.ccCmd、sendemail.headerCmd）以及这些选择器之外由 argv 驱动的行为，例如由 --compose/--annotate 运行的编辑器或传递给 git format-patch 的选项，仍属于委托权限。兼容性： 一律拒绝 git filter-branch，包括 git filter-branch --help。这些只是有限的纵深防御规则，并不能完全约束 Git：钩子、编辑器、合并策略、textconv 驱动程序以及其他由 argv 或配置驱动的助手（包括 difftool 命令和 submodule foreach）仍属于委托权限。 这些拒绝规则针对的是一份有限的已知名称和参数形式列表；该策略无法识别所有能够启动辅助程序或其他程序的程序。对于你加入允许列表的程序，其自身委派的行为仍会保留：make 配方会运行自己的命令，dd/tee 会以服务器进程的操作系统权限读写其自身操作数中指定的路径（of=、文件参数）。这些由程序自身执行的操作属于委派行为，并未受到限制，也不会被验证机制阻止。处理恶意或不可信工作负载时，需要采用外部的最小权限操作系统或容器隔离。

对于 tar 及其 gtar/bsdtar 别名，会拒绝所有会让 tar 启动其他程序的选项：--checkpoint-action（所有操作，不仅是 exec=）、--use-compress-program/-I、--to-command、--rsh-command、--rmt-command 和 --info-script/--new-volume-script/-F。拒绝规则适用于分隔形式和 = 形式的值、候选项中包含上述名称的所有缩写（例如 --use-comp、--to、--rm）、短选项组合中任意位置的 -I/-F，以及 cIf 这类位于首位的旧式单词；也适用于放在操作数之后的选项。无论可执行文件名称为何，都会分别按照 GNU tar 1.34 和 bsdtar 3.5.3/3.7.4 的选项语法检查参数；只要其中一种解释会触发辅助程序选项，就会拒绝该命令。例如，bsdtar 将 -H/-L 视为标志，并将 -Wname 视为 --name；而 GNU tar 会将它们视为需要取值的选项。由无害选项读取的值属于数据；独立且未被读取的 -- 会结束选项解析；普通的创建、列表、提取操作、内置压缩开关（-z/-j/-J）以及数值型 --checkpoint=N 间隔仍然允许。**兼容性：**现在会拒绝 --checkpoint-action=dot 等非 exec 检查点操作；如果某个参数列表在一种 tar 方言中无害，但在另一种方言中会运行辅助程序，也会被拒绝。这是一套有限的规则，并非 tar 沙箱：不会验证文件列表和其他 tar 文件系统操作。

请使用服务器受限的重定向来写入排序后的输出，而不要使用 sort -o：["sort", "input", ">", "output"] 会将目标限制在请求的工作目录内，而 sort -o 会直接写入进程可访问的任意路径。使用 -- 分隔符后，仍可使用类似选项的文件名，例如 ["sort", "--", "--output=data"]。

这项加固是针对已知危险参数形式的尽力纵深防御。它并不全面，也不是针对任意不可信命令执行的完整沙箱。当请求或文件内容可能源自不可信输入时，请参阅可信执行约定，了解所需的外部隔离措施。

子进程环境

命令在隔离的子进程环境中运行。服务不会将父进程的完整环境传递给子命令，因此默认情况下，API 令牌、凭据和 SECRET_TOKEN 等无关变量不会传递。

默认情况下，子进程环境仅包含执行命令所需的最少启动键：POSIX 系统上的 PATH，以及适用时用于 Windows 进程启动的键（COMSPEC、PATHEXT、SYSTEMROOT 和 WINDIR）。

子进程的 PATH 不会从服务进程继承，而是按以下优先级确定：

1. 当 PATH 在 MCP_SHELL_CHILD_ENV_ALLOWLIST 中明确列出时，使用单次调用的 envs 中的 PATH 值；否则使用父进程的 PATH。传递的值（包括空字符串）会保持不变。
2. 否则，使用非空白的 MCP_SHELL_SAFE_PATH，并严格按配置使用（不进行修剪）。
3. 否则，在 POSIX 系统上使用默认值 /usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin。若 MCP_SHELL_SAFE_PATH 未设置、为空或仅包含空白字符，则使用此默认值。

在 POSIX 系统上，像 git 这样的裸命令名会通过此子进程 PATH 进行解析，因此不会选中服务自身 PATH 中更靠前的可执行文件；如果安全 PATH 中缺少某个命令，命令会失败，而不会回退到父进程的 PATH。因此，在系统目录之外安装的工具（例如 Apple Silicon 上的 Homebrew、~/.local/bin 或版本管理器的 shim）需要将其目录添加到 MCP_SHELL_SAFE_PATH，或通过 MCP_SHELL_CHILD_ENV_ALLOWLIST="PATH" 显式委托：

MCP_SHELL_SAFE_PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin" \
ALLOW_COMMANDS="git,rg" \
uvx mcp-shell-server

委托 PATH 需要由运维人员主动选择：未启用时，单次调用 envs 中的 PATH 值会被忽略。在 Windows 上，非空白的 MCP_SHELL_SAFE_PATH 会用作子进程的 PATH；否则保留父进程的 PATH（仅在其不存在时回退到 os.defpath）。Windows 原生可执行文件搜索不会遵循子进程环境中的 PATH，因此此设置不能保证在 Windows 上进行安全查找。

使用 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

只有在 MCP_SHELL_CHILD_ENV_ALLOWLIST 中列出的键才会被转发。日志会对类似机密的名称进行防护处理；除非你有意让子命令读取该机密，否则不应将其加入允许列表。

结构化审计日志

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

审计元数据包括：

• timestamp、duration 和 result_type
• 命令名称和经过脱敏的 argv
• 解析后的工作 directory
• stdin/stdout/stdout 追加的重定向标志
• 提供时经过脱敏的单次调用环境覆盖元数据
• 生效的 timeout 和 output_limit
• stdout_bytes 和 stderr_bytes
• 可用时的 return_code
• 适用时的 rejection_reason 或 error_type

审计日志不会包含原始 stdout 或 stderr 内容。类似机密的 argv，以及名称中包含 SECRET、TOKEN、PASSWORD、PASSWD、API_KEY、ACCESS_KEY、PRIVATE_KEY、KEY、CREDENTIAL 或 AUTH 等标记的环境变量名称或值，都会替换为 [REDACTED]。较长的非数字值会以短 SHA-256 摘要表示，而非原始值。

请求格式

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

# Basic command execution in the server process CWD
{
    "command": ["ls", "-l"]
}

# Command with a relative working directory resolved from the server process CWD
{
    "command": ["pwd"],
    "directory": "subproject"
}

# 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
}

响应格式

成功响应：

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

错误响应：

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

失败的单条命令：当命令以非零状态退出时，MCP 工具结果的 isError: true，其文本以 Error executing command: Command failed with exit status N 开头（如果进程因信号而被终止，则以 Error executing command: Command terminated by signal N 开头），后面附有命令的标准输出和标准错误（若有）。此输出会返回给客户端，但不会记录其内容。成功的命令（退出状态为 0）会原样返回其标准输出和标准错误。管道失败处理方式不变，且不会以相同方式保留输出。

安全性

以下措施是服务自身可强制执行的边界；它们不是操作系统沙箱。命令名称允许列表控制服务直接启动哪些可执行文件，但获准程序仍会以服务进程的操作系统权限运行，可能读取可访问的文件、占用 CPU、启动子进程或访问网络。有关这些措施能限制和不能限制的内容，以及处理不可信输入所需的外部隔离，请参阅受信任的执行契约。

1. 命令白名单：只能执行明确允许的命令名称或与 ALLOW_PATTERNS 条目完全匹配的命令。这只允许可执行文件名称；不会限制获准程序自身的行为。
2. 默认参数加固（非穷尽式纵深防御）：默认拒绝已知的可执行程序调用途径，例如 shell／解释器、JS 运行时（deno、bun）、命令包装程序（setarch、strace、valgrind、timeout 等）、env、xargs、find -exec／-execdir／-ok／-okdir、awk system()、tar 外部程序选项（--checkpoint-action、--use-compress-program／-I、--to-command、--rsh-command、--rmt-command、--info-script／--new-volume-script／-F，适用于 GNU 和 BSD tar 语法）、GNU sort --compress-program／-o／--files0-from／-T、Git 外部程序选项（包括 git grep -O、git rebase -x／--exec、git filter-branch、git bisect run，以及 git send-email 的 --sendmail-cmd／--to-cmd／--cc-cmd／--header-cmd 和类似程序的 --smtp-server 值），以及任何全局 git -c <name=value> 或 git -c<name=value> 配置覆盖，即使命令名称已列入允许列表也是如此。这是一份有限列表，并不能识别所有能够启动辅助程序的程序；获准的 make 配方以及 dd／tee 自有的文件 I/O 仍属于委托权限范围。
3. 不执行 Shell 字符串：普通命令和管道通过 asyncio.create_subprocess_exec(*argv) 执行；不会将用户控制的字符串传递给 shell。
4. 受限重定向：重定向路径必须相对于 directory；绝对路径、.. 路径遍历和符号链接逃逸会在打开文件前被拒绝。
5. 环境隔离：子进程仅接收最小化环境，以及 MCP_SHELL_CHILD_ENV_ALLOWLIST 中列出的名称。默认不会继承令牌等父进程机密。仅接受针对明确列入允许列表的名称设置的单次调用 envs 值。
6. 执行限制：MCP_SHELL_DEFAULT_TIMEOUT_SECONDS 默认为 30 秒，MCP_SHELL_MAX_TIMEOUT_SECONDS 默认为 300 秒，MCP_SHELL_OUTPUT_LIMIT_BYTES 默认为每个已捕获的标准输出／标准错误流 1 MiB。客户端超时会限制在服务端最大值内；未指定超时时间时使用默认值。超时或超出输出上限的进程会先被终止并回收，然后返回明确的超时／输出上限错误。
7. 审计日志：每次调用都会针对成功、拒绝、超时、输出上限和进程错误结果生成结构化审计元数据。类似机密的 argv 值会被编辑；不会记录标准输出／标准错误的内容。

与安全相关的环境变量

变量	默认值	说明
ALLOW_COMMANDS / ALLOWED_COMMANDS	空	允许执行的命令名称，以逗号分隔
ALLOW_PATTERNS	空	以逗号分隔的正则表达式模式，使用 fullmatch() 与命令名称进行匹配
MCP_SHELL_DEFAULT_TIMEOUT_SECONDS	30	客户端未提供 timeout 时使用的超时时间
MCP_SHELL_MAX_TIMEOUT_SECONDS	300	客户端可接受的最大有效超时时间
MCP_SHELL_OUTPUT_LIMIT_BYTES	1048576	每个进程捕获的 stdout/stderr 最大字节数
MCP_SHELL_CHILD_ENV_ALLOWLIST	空	允许传递给子进程的父级或单次调用环境变量，以逗号分隔
MCP_SHELL_SAFE_PATH	/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin	提供给子进程的 PATH；除非 PATH 在 MCP_SHELL_CHILD_ENV_ALLOWLIST 中，否则也用于 POSIX 命令查找；空值将使用默认值

开发

设置开发环境

1. 克隆仓库

git clone https://github.com/yourusername/mcp-shell-server.git
cd mcp-shell-server

2. 安装依赖（包括测试所需依赖）

pip install -e ".[test]"

运行测试

pytest

API 参考

请求参数

字段	类型	必填	说明
command	string[]	是	以数组元素形式提供的命令及其参数
stdin	string	否	传递给命令的输入
directory	string	否	工作目录；省略时使用服务进程的 CWD，相对路径以该服务进程的 CWD 为基准解析
timeout	integer	否	最大执行时间（秒）

响应字段

字段	类型	说明
stdout	string	命令的标准输出
stderr	string	命令的标准错误输出
status	integer	退出状态码
execution_time	float	执行所用时间（秒）
error	string	错误消息（仅在失败时出现）

要求

• Python 3.11 或更高版本
• mcp>=1.1.0

许可证

MIT 许可证——详情请参阅 LICENSE 文件