mcp-shell-sudo

用 Python 编写的 Linux MCP 服务器，通过 argv 执行本地命令，支持通过 PASSWORD_SUDO 进行非交互式 sudo，通过 ALLOW_COMMANDS 提供可选的命令白名单，并可使用 Bubblewrap 将文件系统写入限制在 WORK_DIR 内。

要求

• Linux。

• Python 3.11+。

• 建议使用 uv。

• MCP Python SDK 2.0.0。

• 如需执行提权命令，则需要 sudo。

• 如果配置了 WORK_DIR，则需要 bubblewrap。

在 Debian/Ubuntu 上：

sudo apt update
sudo apt install -y bubblewrap

Related MCP server: MCP Process Server

环境变量

PASSWORD_SUDO

运行 MCP 服务器的用户的密码。

• 为空或未设置：服务器绝不会自行生成或交互式请求密码。以 sudo 为前缀的命令使用 sudo -n 执行，仅当已存在有效的缓存凭据或配置了 NOPASSWD 规则时才会生效。

• 已设置：sudo 以 -S 执行，密码通过 stdin 提供，绝不会出现在 argv 或日志中。

示例：

"PASSWORD_SUDO": "my-password"

支持的形式为：

["sudo", "id"]

不接受自定义 sudo 标志，例如 sudo -u postgres ...。这样可以避免策略层必须解释完整的 sudo 命令语法。

WORK_DIR

可选的工作目录。

• 为空或未设置：MCP 服务器可以在工具调用中指定的任何现有目录下工作。

• 已设置：服务器进入严格模式。directory 必须解析到 WORK_DIR 内部，并且每个进程都在 Bubblewrap 挂载命名空间中运行，其中 / 为只读，WORK_DIR 以读写方式挂载，/tmp 和 /run 为临时目录。

仅使用 cwd 不足以保证这种隔离。进程仍然可以写入 /etc、/home/...，或跟随符号链接到项目外部。因此，如果配置了 WORK_DIR 但 bwrap 不可用，服务器会在启动时失败。

在此模式下，sudo 会被拒绝，因为主机级别的权限提升与文件系统写入限制在工作区内的保证不兼容。

ALLOW_COMMANDS

以逗号分隔的可执行文件名称列表。

"ALLOW_COMMANDS": "git,ls,cat,grep,python,node,pnpm"

• 为空或未设置：允许所有可执行文件。

• 已设置：仅允许列表中的确切可执行文件名称，并且必须按名称调用，而不能通过 /usr/bin/git 等路径调用。

• 如果命令以 sudo 开头，则验证 sudo 之后的实际可执行文件。

白名单适用于可执行文件，而非参数。允许 bash、python、node、env 或其他能够执行进程的工具，会显著扩大 MCP 客户端可以执行的操作范围。

安装

uv sync

用于开发：

uv sync --extra dev

手动执行

uv run mcp-shell-sudo

传输方式为 stdio。日志绝不会写入 stdout，以免破坏 JSON-RPC 消息；日志写入 stderr。

MCP 配置

无限制命令并启用 sudo 的示例：

{
  "mcpServers": {
    "shell": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/mcp-shell-sudo",
        "run",
        "mcp-shell-sudo"
      ],
      "env": {
        "PASSWORD_SUDO": "YOUR_PASSWORD",
        "WORK_DIR": "",
        "ALLOW_COMMANDS": ""
      }
    }
  }
}

限制在特定项目中的示例：

{
  "mcpServers": {
    "shell-project": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/mcp-shell-sudo",
        "run",
        "mcp-shell-sudo"
      ],
      "env": {
        "PASSWORD_SUDO": "",
        "WORK_DIR": "/home/user/projects/app",
        "ALLOW_COMMANDS": "git,ls,cat,grep,find,python,node,pnpm"
      }
    }
  }
}

shell_execute 工具

基本输入：

{
  "command": ["ls", "-la"]
}

带工作目录：

{
  "command": ["git", "status"],
  "directory": "backend"
}

带 stdin：

{
  "command": ["cat"],
  "stdin": "hello\n"
}

带 sudo：

{
  "command": ["sudo", "id"]
}

响应：

{
  "stdout": "uid=0(root) gid=0(root) groups=0(root)\n",
  "stderr": "",
  "status": 0,
  "execution_time": 0.031,
  "timed_out": false,
  "output_limited": false
}

shell_config 工具

返回有效的非机密配置。

它绝不会返回 PASSWORD_SUDO；仅指示是否已配置 sudo 密码。

已实现的安全措施

• 使用 create_subprocess_exec；不使用 shell=True。

• command 作为显式 argv 数组传递。

• sudo 密码绝不会出现在 argv、响应、日志或子进程环境中。

• 如果未配置 PASSWORD_SUDO，sudo -n 可防止进程在等待交互式密码提示时挂起。

• ALLOW_COMMANDS 验证简单的 sudo 调用之后的实际可执行文件。

• 使用固定且精简的 PATH，避免从 . 或任意继承的路径解析可执行文件。

• 使用精简的子进程环境，而不是继承整个 MCP 服务器环境。

• 每次调用超时：默认 60 秒，最大 600 秒。

• 输出限制：每个流 2 MiB。如果超出限制，整个进程组将被终止。

• 进程在新会话中运行，超时时整个进程组会被终止。

• WORK_DIR 使用 Bubblewrap，如果无法提供隔离，则默认失败关闭。

重要限制

1. ALLOW_COMMANDS="" 意味着以运行 MCP 服务器的用户的权限执行任意命令。如果同时配置了 PASSWORD_SUDO，MCP 客户端可以请求以 root 身份执行操作。仅在你控制的客户端和模型下使用此配置。

2. 可执行文件白名单不会在语义上验证命令参数。python、node、bash、sh、perl 及类似工具实际上等同于允许任意代码执行。

3. WORK_DIR 限制了可写的文件系统位置，但并非旨在充当虚拟机或网络沙箱。具有网络访问权限的命令仍可能修改其拥有有效凭据的远程资源。

4. 存储在 MCP 客户端配置中的 PASSWORD_SUDO 仍然是存储在该文件中的机密。使用 chmod 600 限制文件权限，并且切勿将其提交到版本控制。

测试

uv run --extra dev pytest
uv run --extra dev ruff check .