Quick MCP Shell

quick-mcp-shell 是一个本地 stdio MCP Server，供 Amazon Quick 调用本机 shell 命令和 Python 脚本。

警告：这是一个高权限工具。它执行的命令拥有启动它的用户权限。MCP_SHELL_ALLOWED_ROOT 仅限制工作目录（cwd），不是文件系统或网络沙箱。只应连接到受信任的本地 MCP 客户端，绝不能暴露到公网，也不要向不受信任的提示词或用户开放。

安装 uv

Amazon Quick 通过 uvx 自动下载并运行本工具，无需手动安装 Python 包。

Windows（PowerShell）

winget install --id=astral-sh.uv -e

macOS（需已安装 Homebrew）

brew install uv

Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

安装后执行 uvx --version 确认命令可用。

配置 Amazon Quick

在 Amazon Quick 中打开 Settings → Capabilities → MCP Servers，编辑配置文件：

• Windows：C:\Users\你的用户名\.aws\amazonq\mcp.json
• macOS / Linux：~/.aws/amazonq/mcp.json

将下列内容合并到 mcpServers。必须把 MCP_SHELL_ALLOWED_ROOT 改为你希望允许作为工作目录的实际路径。

Windows 示例

{
  "mcpServers": {
    "shell": {
      "command": "uvx",
      "args": ["--from", "quick-mcp-shell==0.3.0", "quick-mcp-shell"],
      "description": "在指定工作目录内执行受信任的本地 shell 命令和 Python 脚本。",
      "env": {
        "MCP_SHELL_ALLOWED_ROOT": "D:\\workspace\\my-project",
        "MCP_SHELL_MAX_TIMEOUT_SECONDS": "60",
        "MCP_SHELL_MAX_OUTPUT_CHARS": "100000"
      }
    }
  }
}

macOS / Linux 示例

{
  "mcpServers": {
    "shell": {
      "command": "uvx",
      "args": ["--from", "quick-mcp-shell==0.3.0", "quick-mcp-shell"],
      "description": "在指定工作目录内执行受信任的本地 shell 命令和 Python 脚本。",
      "env": {
        "MCP_SHELL_ALLOWED_ROOT": "/Users/your-name/workspace/my-project",
        "MCP_SHELL_MAX_TIMEOUT_SECONDS": "60",
        "MCP_SHELL_MAX_OUTPUT_CHARS": "100000"
      }
    }
  }
}

Linux 用户可将示例路径替换为 /home/your-name/workspace/my-project。保存配置并重启 Amazon Quick。

可用工具

run_command

执行本机 shell 命令。

示例：让 Amazon Quick 在项目目录中执行 git status，或运行项目已有的测试命令。

run_python_script

在所选工作目录中使用本工具自身的 Python 解释器执行一段 Python 脚本。参数与 run_command 相同，只是把 command 替换为 script。

配置项

本地检查

在终端中运行以下命令可检查当前配置：

uvx --from quick-mcp-shell==0.3.0 quick-mcp-shell --allow-root /你的工作目录 doctor

Windows 示例：

uvx --from quick-mcp-shell==0.3.0 quick-mcp-shell --allow-root "D:\workspace\my-project" doctor

安全边界

• 不要将本工具部署为远程 HTTP 服务或暴露到公网。
• 不要把允许根目录设为系统盘根目录、用户主目录或包含密钥的目录。
• 不要把本工具交给不受信任的模型、插件、用户输入或自动化流程。
• 命令和脚本可访问当前用户能访问的资源；允许根目录不是安全沙箱。
• 固定版本号。升级前先阅读发布说明，并在隔离的项目目录中验证。