Skip to main content
Glama
local-exec-mcp

local-exec-mcp

README.md
# local-exec-mcp

An MCP server that runs shell commands on hosts where OS-level sandboxing is unavailable — Android/Termux, PRoot containers, kernels older than 5.13, or any box where `bubblewrap` / `landlock` / `unshare(2)` are missing or blocked.

Zero dependencies. One file. ~420 lines. Easy to audit before you trust it.

一个 MCP 服务器:在无法使用操作系统级沙箱的主机上执行 shell 命令 —— 比如 Android/Termux、PRoot 容器、内核低于 5.13 的系统,以及任何缺少或禁用 `bubblewrap` / `landlock` / `unshare(2)` 的环境。

零依赖、单文件、约 420 行,信任它之前很容易审计。

> 本 README 为中英双语:英文原文在前,中文译文紧随其后。
> This README is bilingual: English first, Chinese translation follows.

## Why this exists 为什么需要它

Most agent tooling assumes it can build a real sandbox: `bwrap`, Landlock, user namespaces. On some hosts none of that works. A concrete case:

大多数 agent 工具链都假定自己能够构建真正的沙箱:`bwrap`、Landlock、用户命名空间。但在某些主机上这些全都用不了。一个具体例子:

| Probe 探测 | Result 结果 |
|---|---|
| `bwrap` / `firejail` / `nsjail` | not installed / 未安装 |
| `unshare -m` / `unshare -p` | `EPERM` (blocked by PRoot) / 被 PRoot 拦截 |
| `unshare -Ur` | `EINVAL` |
| `landlock_create_ruleset` | `ENOSYS` (needs kernel 5.13+, host is 4.19) / 需要内核 5.13+,而主机是 4.19 |

When that happens, agent shells either crash outright or refuse to run. This server takes the other path: **run the command, but be honest about the reduced guarantees** — every invocation is audited, obviously destructive commands and writes into protected paths are blocked by policy, and nothing pretends to be isolation.

遇到这种情况,agent 的 shell 要么直接崩溃,要么拒绝运行。本服务器选择另一条路:**照常执行命令,但如实说明保障被削弱了** —— 每次调用都会审计,明显破坏性的命令以及写入受保护路径的操作会被策略拦截,绝不假装这就是隔离。

## What this is not 它不是什么

**It is not a sandbox.** The guard is regex policy plus path checks. It stops mistakes and typos; it does not stop a determined command from doing whatever it wants — `base64 -d | bash`, a script written in two steps, or anything that does its damage inside a child process will sail right past it.

**它不是沙箱。** 这层防护只是正则策略加路径检查:它能拦住误操作和手滑打错,但拦不住一条铁了心的命令去做任何事 —— `base64 -d | bash`、分两步写入的脚本,或者在子进程里搞破坏的命令,都能轻松绕过它。

If your host supports real isolation, use it instead. Reach for this only when it does not.

如果你的主机支持真正的隔离,请优先使用真正的隔离;只有在不支持时再来考虑它。

## Install 安装

Requires Node.js >= 18.

需要 Node.js >= 18。

```bash
npx -y local-exec-mcp
```

Or register it manually. Claude Desktop / Cursor / Cline style:

或者手动注册。Claude Desktop / Cursor / Cline 风格:

```json
{
  "mcpServers": {
    "local-exec": {
      "command": "npx",
      "args": ["-y", "local-exec-mcp"]
    }
  }
}
```

Local checkout:

从本地检出的源码运行:

```json
{
  "mcpServers": {
    "local-exec": {
      "command": "node",
      "args": ["/absolute/path/to/server.js"]
    }
  }
}
```

## Tools 工具

### `run`

| Field 字段 | Type 类型 | Notes 说明 |
|---|---|---|
| `command` | string | required / 必填 |
| `cwd` | string | absolute path, defaults to `$WB_EXEC_CWD` or the process cwd / 绝对路径,默认取 `$WB_EXEC_CWD` 或进程当前目录 |
| `timeout_ms` | number | default 120000, max 600000 / 默认 120000,最大 600000 |
| `force` | boolean | bypass the policy guard (still audited) / 绕过策略防护(仍会审计) |

Returns exit code, stdout and stderr in one text block. Output above 180 KB is truncated in the middle. Timeouts and cancellations kill the whole process group, not just the direct child.

在一个文本块里返回退出码、stdout 与 stderr。超过 180 KB 的输出会从中间截断。超时和取消会杀掉整个进程组,而不只是直接子进程。

Honours MCP `notifications/cancelled` and emits `notifications/progress` when the caller supplies a `progressToken`.

支持 MCP 的 `notifications/cancelled`;当调用方提供 `progressToken` 时会发出 `notifications/progress`。

### `audit`

Returns the most recent entries from today's audit log.

返回今天审计日志中最近的条目。

## Policy 策略

Blocked unless `force: true`:

除非 `force: true`,否则以下操作会被拦截:

- `rm -rf /`, `--no-preserve-root`, `mkfs*`, `dd of=/dev/block*`, `> /dev/block*`, `reboot`/`poweroff`/`shutdown`/`halt`, `kill -9 1`, fork bombs, `chmod -R 777 /`
- Writes targeting `/media/sd`, `/data`, `/system`, `/vendor`, `/opt/WorkBuddy`, `~/.dsh`, `~/.local-exec-mcp`

- `rm -rf /`、`--no-preserve-root`、`mkfs*`、`dd of=/dev/block*`、`> /dev/block*`、`reboot`/`poweroff`/`shutdown`/`halt`、`kill -9 1`、fork 炸弹、`chmod -R 777 /`
- 针对 `/media/sd`、`/data`、`/system`、`/vendor`、`/opt/WorkBuddy`、`~/.dsh`、`~/.local-exec-mcp` 的写入

Command-position matching means `echo "reboot is a word"` passes, while a bare `reboot` does not.

按命令位置匹配:`echo "reboot is a word"` 能通过,而裸的 `reboot` 不能。

## Audit 审计

Append-only NDJSON, one file per day:

只追加的 NDJSON,每天一个文件:

```
$WB_EXEC_AUDIT_DIR || ~/.local-exec-mcp/audit/audit-YYYY-MM-DD.ndjson
```

Each entry records timestamp, command, cwd, exit code, signal, duration, and whether it was denied, timed out, cancelled, or forced.

每条记录包含时间戳、命令、cwd、退出码、信号、耗时,以及是否被拒绝、超时、取消或强制放行。

## Environment variables 环境变量

| Variable 变量 | Purpose 用途 |
|---|---|
| `WB_EXEC_CWD` | default working directory / 默认工作目录 |
| `WB_EXEC_SHELL` | override the shell binary / 覆盖 shell 可执行文件 |
| `WB_EXEC_AUDIT_DIR` | override the audit directory / 覆盖审计目录 |

`ulimit` guards (CPU seconds, 2 GiB max file size) are applied on POSIX only.

`ulimit` 保护(CPU 秒数、最大文件 2 GiB)只在 POSIX 上生效。

## Compatibility 兼容性

- Linux, macOS: any Node >= 18, `/bin/bash` or `/bin/sh`
- Windows: runs commands through `%COMSPEC%`; process-group kill and `ulimit` are not available
- Android / Termux / PRoot: primary target — this server exists because sandboxed executors tend to fail there

- Linux、macOS:任意 Node >= 18,`/bin/bash` 或 `/bin/sh`
- Windows:通过 `%COMSPEC%` 执行命令;不支持进程组终止与 `ulimit`
- Android / Termux / PRoot:主要目标场景 —— 本服务器正是因为沙箱化执行器在这些环境下常常失败而存在

## Threat model 威胁模型

Trusted local operator, untrusted model output. The goal is to keep an agent from wrecking the machine by accident, and to leave a trail when it does something surprising. It is not designed to contain a malicious operator who already has shell access — at that point they can edit this file.

可信的本地操作者 + 不可信的模型输出。目标是不让 agent 意外把机器搞坏,并在它做出意外举动时留下痕迹。它并不打算防范已经拿到 shell 访问权的恶意操作者 —— 到那一步,对方直接改这个文件就行了。

## License 许可

MIT