Skip to main content
Glama
local-exec-mcp

local-exec-mcp

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

Related MCP server: mcp-shell-server

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。

npx -y local-exec-mcp

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

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

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

Local checkout:

从本地检出的源码运行:

{
  "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

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP clients to run shell commands on the host and retrieve exit code, stdout, and stderr, with hardened authentication and an encrypted audit log.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP-compatible agents to execute bash and subprocess commands through a zero-dependency sandbox guard that blocks destructive system mutations, path traversals, reverse shells, and other unsafe execution patterns.
      7
      MIT