Skip to main content
Glama
Sign In
deenesjakoruzh
mcp-shell-sudo

mcp-shell-sudo

by eaangrino
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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-shell

环境变量

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 .

Available Tools

2 tools
shell_configA

Return the effective non-secret shell policy configuration.

NameRequiredDescriptionDefault

No parameters

Output Schema

NameRequiredDescription

No output parameters

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description serves as the only behavioral disclosure. It implies a read-only operation ('Return') but does not explicitly state that it has no side effects or that it is safe. It does clarify that secrets are excluded, which is a useful constraint. However, it does not mention any authentication or permission requirements, which could be relevant.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that front-loads the action ('Return') and specifies the resource. There is no wasted verbiage.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that there are no parameters, the description sufficiently conveys the tool's function. The existence of an output schema covers return details, so the description need not elaborate. It does not mention usage context, but that is already addressed in usage_guidelines; for a simple config retrieval, this is complete enough.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, so the description is not required to explain parameter syntax. The phrase 'non-secret' adds context about the output scope but does not relate to parameters. For a parameterless tool, this is adequate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Return') and a clear resource ('effective non-secret shell policy configuration'). It distinguishes itself from the sibling tool by nature (configuration retrieval vs. execution), though it does not explicitly name the alternative. The purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given for when to use this tool versus the sibling shell_execute. An agent must infer that this is for reading configuration, not executing commands. The description does not mention any prerequisites, alternatives, or context for selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

shell_executeA

Execute one command as an argv array.

Args: command: Executable and arguments, for example ["ls", "-la"] or ["sudo", "systemctl", "status", "ssh"]. Shell syntax is not interpreted. stdin: Optional text sent to the command's standard input. directory: Optional working directory. With WORK_DIR configured, this path must resolve inside WORK_DIR. Without WORK_DIR, any existing directory may be used. timeout: Execution timeout in seconds. Values above 600 seconds are capped at 600.

Returns: stdout, stderr, exit status, execution time, timeout flag, and output-limit flag.

NameRequiredDescriptionDefault
stdinNo
commandYes
timeoutNo
directoryNo

Output Schema

NameRequiredDescription

No output parameters

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It mentions that shell syntax is not interpreted, that the timeout is capped at 600 seconds, and that directory paths must resolve inside WORK_DIR if configured. However, it does not warn about the potentially destructive nature of executing arbitrary commands or the side effects of the executed process, which is a notable omission for a command execution tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is structured with a clear one-line summary, a detailed 'Args' section, and a 'Returns' section. It is appropriately detailed for a tool with multiple parameters but remains readable. The example for the command parameter adds clarity without bloat.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the essential invocation details: command format, directory constraints, timeout cap, and the return fields (stdout, stderr, exit status, etc.). It does not explain prerequisites such as the meaning of WORK_DIR, but this is likely a global configuration rather than tool-specific. Given the presence of an output schema (though not shown), the return-field listing is sufficient. Overall, it provides enough for an agent to call the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema provides no descriptions for any of the four parameters (schema coverage 0%), so the description must fully compensate. It does so thoroughly by explaining each parameter: the command array with examples, optional stdin, directory restrictions relative to WORK_DIR, and timeout cap. This adds substantial meaning beyond the schema's type definitions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Execute one command as an argv array.' It clearly distinguishes from the sibling tool 'shell_config' by implying execution vs. configuration, and provides a concrete example to clarify the argv format.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides clear guidance on how to invoke the tool, including the requirement to pass an argv array rather than shell syntax, and clarifies timeout and directory constraints. However, it does not explicitly state when to prefer this tool over shell_config, though the purpose difference is evident from the name and description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 2 tool updatesv0.1.0
    • First observedshell_config
    • First observedshell_execute
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

A3.9/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have completely distinct purposes: one executes commands and the other returns configuration. There is no overlap or potential for misselection between them.

Naming Consistency5/5

Both tools follow the same snake_case verb_noun pattern (shell_execute, shell_config). The naming is clear, predictable, and consistent.

Tool Count3/5

With only two tools, this server feels thin, but the narrow scope (shell execution and configuration) justifies the limited surface. It is at the lower edge of what is reasonable, as stated in the calibration.

Completeness4/5

The tool surface covers the core functionality of executing shell commands and retrieving configuration. There is no obvious missing operation for the stated purpose; the only minor gap might be a way to list allowed commands or test, but that is not essential.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-shell

    imajeure
    A
    license
    Not graded
    quality
    D
    maintenance
    Provides a secure, token-authenticated command execution tool over MCP Streamable HTTP, with a default-deny allowlist and shell metacharacter rejection.
    11 npm
    1
    Apache 2.0