Metadata-Version: 2.5
Name: quick-mcp-shell
Version: 0.4.1
Summary: A local stdio MCP server for trusted shell and Python execution
Project-URL: Homepage, https://pypi.org/project/quick-mcp-shell/
Author: Quick MCP Shell maintainers
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: System :: Shells
Requires-Python: >=3.11
Requires-Dist: mcp<2.0.0,>=1.2.0
Description-Content-Type: text/markdown

# Quick MCP Shell

Amazon Quick 的执行环境是一个隔离的sandbox，无法调用本地命令，需要借助MCP才能够在本机执行 shell 命令和 运行Python 脚本。
例如：本地安装了 lark-cli 操作飞书，但是Quick无法直接使用 lark-cli 命令，可以通过该MCP执行 lark-cli 命令。

## 安装 uv

Amazon Quick 使用 `uvx` 启动本工具。

- Windows(PowerShell)：`winget install --id=astral-sh.uv -e`
- macOS：`brew install uv`
- Linux：`curl -LsSf https://astral.sh/uv/install.sh | sh`

执行 `uvx --version` 确认 uvx 已成功安装。

## 配置 Amazon Quick

打开 **Settings → Capabilities → MCP Servers**，在配置文件的 `mcpServers` 中加入以下配置：

```json
{
  "shell": {
    "command": "uvx",
    "args": ["--from", "quick-mcp-shell==0.4.1", "quick-mcp-shell"]
  }
}
```


## 工具

配置完成后，Amazon Quick 会自动获得下面两个工具，并在需要时自行调用；你只需用自然语言向 Quick 描述需求，无需手动调用。

- `run_command`：执行 shell 命令。Windows 上通过 `cmd.exe` 执行（不是 PowerShell），macOS/Linux 上通过 `/bin/sh` 执行。
- `run_python_script`：执行 Python 脚本。使用本工具自带的隔离解释器，项目里安装的第三方包（如 pandas）不可用；需要项目依赖时让 Quick 改用 `run_command`。

两个工具都支持可选的 `cwd` 和 `timeout` 参数，由 Quick 在调用时传入：不传 `cwd` 时使用当前用户的主目录，相对路径也相对主目录解析，传入绝对路径时可指定任意存在的目录；`timeout` 默认 30 秒、最大 60 秒，超时会终止整个进程树。

可选环境变量：

| 变量 | 默认值 | 作用 |
|---|---:|---|
| `MCP_SHELL_MAX_TIMEOUT_SECONDS` | `60` | 单次调用允许的最大超时秒数。 |
| `MCP_SHELL_MAX_OUTPUT_CHARS` | `100000` | 返回结果的最大字符数，超出时保留首尾两段。 |

检查启动环境：

```bash
uvx --from quick-mcp-shell==0.4.1 quick-mcp-shell doctor
```

## 安全边界

本工具不限制命令访问的目录。命令可以切换目录或使用绝对路径；若需要真正的访问隔离，请使用受限系统账户、容器或操作系统权限控制。
