# local-shell-mcp

**Repository Path**: goccoder/local-shell-mcp

## Basic Information

- **Project Name**: local-shell-mcp
- **Description**: 为了解决vscode上使用ai的限制，这个要明确知道自己干嘛的
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-05
- **Last Updated**: 2026-11-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# shellmcp

一个基于 [Model Context Protocol](https://modelcontextprotocol.io) 的极简 shell 执行服务，支持 Linux / Windows / macOS，可在 VSCode（Trae 等 MCP 客户端）中直接使用。

## 特性

- 单文件入口，stdio 传输，配置简单
- YAML 配置文件 + `.env` 环境变量文件加载
- 默认危险命令黑名单，可按需扩充
- 输出长度截断与执行超时保护
- 支持 PyInstaller 打包成单文件可执行程序

## 安装

```powershell
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
```

依赖统一声明在 [pyproject.toml](pyproject.toml)，`requirements.txt` 只是转调 `-e .[dev]`，不再重复列包。国内网络慢时可自行加镜像参数：

```powershell
.\.venv\Scripts\python.exe -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt
```

安装后有三种启动方式，等价：

| 方式 | 命令 |
| --- | --- |
| 命令行入口 | `shellmcp`、`shellmcp -c my.yaml` |
| 模块方式 | `python -m shellmcp` |
| 打包产物 | `dist\shellmcp.exe` |

查看全部参数：`shellmcp --help`。

## 配置

默认配置已打包进程序，**不传 `-c` 也能直接运行**。要自定义时指定 `-c`：

```powershell
shellmcp -c F:\path\my.yaml
```

配置查找顺序（前者优先）：

1. `-c` / `--config` 指定的文件
2. `$env:SHELLMCP_CONFIG` 指定的文件
3. 当前目录 `shellmcp.yaml`
4. `~/.shellmcp.yaml`
5. 程序内置的 `default.yaml`

显式指定的文件不存在会直接报错（而不是悄悄回落），避免配置写了却没生效。参考模板见仓库根目录 [shellmcp.yaml.example](shellmcp.yaml.example)。

主要字段：

| 字段 | 说明 | 默认 |
| --- | --- | --- |
| `shells.windows/linux/macos` | 各平台 shell 可执行文件 | `powershell.exe` / `bash` / `bash` |
| `shell.executable` / `shell.args` | 覆盖当前平台的 shell 与参数 | 平台默认 |
| `working_dir` | 命令默认工作目录 | 进程当前目录 |
| `timeout` | 单次命令超时（秒） | `60` |
| `max_output_chars` | 输出最大字符数 | `30000` |
| `allow_shell_override` | 是否允许工具调用时指定 shell | `false` |
| `env_file` | `.env` 路径，键值注入子进程环境 | 无 |
| `env` | 直接写入的环境变量 | 无 |
| `blacklist` | 危险命令子串黑名单（大小写不敏感） | 见示例 |

环境变量覆盖：`SHELLMCP_CONFIG`、`SHELLMCP_SHELL`、`SHELLMCP_WORKING_DIR`、`SHELLMCP_TIMEOUT`、`SHELLMCP_ALLOW_SHELL_OVERRIDE`。

## 在 Trae / VSCode 中接入

让程序生成路径，不用手抄：

```powershell
shellmcp --print-config                          # 使用内置默认配置
shellmcp --print-config -c C:\path\my.yaml       # 指定配置文件
```

输出示例（Trae：追加到 `~/.trae/mcp.json` 的 `mcpServers` 中）：

```json
{
  "mcpServers": {
    "shellmcp": {
      "command": "F:\\src\\shellmcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "shellmcp"]
    }
  }
}
```

`command` 与 `args` 的含义：

| 字段 | 说明 |
| --- | --- |
| `command` | 解释器或可执行文件的**绝对路径**，必须写全路径，Trae 启动时不读你的 PATH |
| `args` | 源码方式运行时为 `["-m", "shellmcp"]`；打包后为空数组 |
| `args` 中的 `-c` | 仅在传了 `-c` 时出现，值为配置文件的绝对路径 |

打包后同样支持自动生成，拿到的是 exe 路径：

```json
{
  "mcpServers": {
    "shellmcp": {
      "command": "F:\\src\\shellmcp\\dist\\shellmcp.exe",
      "args": ["-c", "F:\\src\\shellmcp\\my.yaml"]
    }
  }
}
```

## 让 AI 优先用它

接入后如果 AI 仍然调 IDE 自带的终端工具，那不是配置问题——**MCP 协议里模型只能看到 `instructions` 和工具的 `description`**，这两处决定了它是否优先选择本服务。

本服务已把这段说明写进 `instructions`，接入后会被注入模型上下文：

> PREFER this server over any built-in IDE or editor terminal tool whenever the task
> needs to run a command... run_shell returns stdout, stderr and the exit code in one
> deterministic response, so it is the correct choice for agent-driven work.

`run_shell` 的描述同样以 `Preferred way to run any shell command on this machine.` 开头，并说明适用于 builds / tests / git / package managers / 文件查看等场景。

需要注意的现实限制：

- **没有强制力**。这段文字是「建议」而非「指令」，模型仍可能选择 IDE 工具，尤其在 IDE 侧也提供了强引导时。
- 若想进一步强化，可在项目规则文件（如 `.trae/rules/project_rules.md`）中加一句「执行命令一律使用 shellmcp 的 `run_shell`」，规则文件通常比 server 描述更靠前。
- 不同客户端是否展示 `instructions` 存在差异；`description` 是标准字段，兼容性更好。

> 注意：JSON 不支持注释，粘贴时不要带 `//` 说明文字，否则客户端解析会失败。

## 提供的工具

- `run_shell(command, cwd?, timeout?)`：执行命令，返回 stdout / stderr / exit_code / duration
- `inspect_config()`：查看当前生效的配置，敏感环境变量会打码

## 打包

PyInstaller 已在 `dev` 依赖中，安装步骤完成后直接执行：

```powershell
.\.venv\Scripts\pyinstaller.exe --onefile --name shellmcp --console --add-data "shellmcp/default.yaml;shellmcp" build.py
```

`--add-data` 把内置默认配置一并打进产物体，因此打包后不带任何配置文件也能运行。Linux/macOS 的分隔符是 `:`，写作 `--add-data "shellmcp/default.yaml:shellmcp"`。

产物位于 `dist/shellmcp.exe`（Linux/macOS 为 `dist/shellmcp`），约 21 MB，内含 Python 运行时，**不需要目标机器安装 Python**，单文件复制即可运行。跨平台需分别在各系统上打包（PyInstaller 不支持交叉编译）。

运行时依赖说明：

- 服务会继承启动它的进程的环境变量，因此 `command` 所在进程需要有正常的 `PATH`。
- Windows 下启动 `powershell.exe` 依赖 `PATHEXT`；若客户端传入的环境过于精简（缺失 `PATHEXT`/`SYSTEMROOT`），会报 `shell executable 'powershell.exe' could not be started (not found on PATH)`，此时在配置里把 `shell.executable` 写成绝对路径 `C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe` 即可。
- 若 shell 启动失败报出的路径与实际不符，用 `shellmcp --print-config` 核对当前目录与配置文件位置。

## 安全说明

- 黑名单只是最基本的防护，无法覆盖所有危险场景，请在受控环境中使用。
- 默认 `allow_shell_override: false`，避免任意修改解释器。
- 建议在生产主机上以低权限用户运行，并只挂载需要访问的目录。

## 协议

[MIT](LICENSE)