Mac Shell MCP Server

Mac Shell MCP Server

一个 MCP 服务，让 AI 客户端运行一小组固定的只读 shell 命令，且仅限于你指定的目录。

它围绕一个理念构建：Agent 无法扩大自身的权限。 没有任何工具可以修改策略，没有 Agent 能消耗的审批队列，也没有 shell 来解释它的参数。

从 1.x 升级？ 2.0.0 是破坏性变更。移除了七个工具，并替换了授权模型。请参阅从 1.x 迁移。1.x 包含由四位独立研究者报告的两个漏洞；请参阅安全公告。

功能

工具	用途
execute_command	在你配置的目录内部运行被允许的命令
execute_external_command	在目录外部运行一条命令 — 需要能够询问人类的客户端
execute_pipeline	串联只读命令，stdout 到 stdin，无需 shell
get_policy	询问什么被允许，而不是猜测后被拒绝
suggest_policy_config	将观察到的使用情况转化为你应用的配置

默认命令

ls pwd echo cat head tail wc grep

每个命令都受限于一份标志允许列表。它们都无法写入文件、执行其他程序，或从环境中读取配置。

find、git、rm 以及所有解释器默认均不可用。 你可以添加其中任何一个，但应了解它们为何不在其中：

• find -fprintf 会将攻击者选择的内容写入攻击者选择的路径，而 find 天然被归类为只读
• git 会执行仓库自身 .git/config 中的命令，且没有任何环境变量可以禁用它
• 解释器（python、perl、awk、node、osascript……）将内联代码作为参数

安装

npm install -g @the_cfdude/mac-shell-mcp

然后创建策略：

mkdir -p ~/.mac-shell-mcp
cp .mac-shell-mcp.sample.json ~/.mac-shell-mcp/config.json
$EDITOR ~/.mac-shell-mcp/config.json    # set allowedRoots to your project
chmod 444 ~/.mac-shell-mcp/config.json  # defence in depth; see Security

添加到你的 MCP 客户端：

{
  "mcpServers": {
    "mac-shell": { "command": "npx", "args": ["-y", "@the_cfdude/mac-shell-mcp"] }
  }
}

未配置任何根目录的全新安装会拒绝一切 — 这是有意为之。每次拒绝都会列出被允许的命令以及配置所在位置，因此第一次失败就会告诉你该怎么做。

配置

策略按以下顺序查找，首个匹配者生效，绝不合并：

1. $MAC_SHELL_MCP_CONFIG — 显式路径
2. ~/.mac-shell-mcp/config.json
3. 宿主环境（MAC_SHELL_ROOTS、MAC_SHELL_COMMANDS）
4. 内置默认值

策略绝不从工作目录读取。 克隆的仓库绝不能提供管辖打开它的 Agent 的策略。

{
  "allowedRoots": ["/Users/you/Projects/my-project"],
  "programDirectories": ["/usr/bin", "/bin", "/usr/sbin", "/sbin"],
  "commands": {
    "grep": {
      "program": "/usr/bin/grep",
      "effect": "read",
      "allowedArgs": ["-i", "-n", "-r", "-l", "-E", "-F"],
      "permission": "allow",
    },
  },
}

permission 为 allow、ask 或 deny。ask 需要提供 MCP elicitation 的客户端 — 这是唯一意味着可以询问人类的能力。若该能力缺失，ask 会变为 deny，绝不会变为 allow。

如何作出判定

授权是 effect × scope，在每次调用时计算。 在项目内执行 grep 是免费的；对 ~/.aws 执行同样的 grep 则不然。仅凭命令名从不下结论。

• 不使用 shell。 execFile 从不传入 shell 选项，因此参数会未经解释地传递给操作系统。没有任何东西会求值 ;、$() 或反引号——这也是为什么带空格、圆括号和方括号的文件名能正常工作。
• 授权的是程序，而不只是参数。 命令会从你的程序目录解析为绝对路径，按该解析后的路径而非 basename 进行匹配，并且如果解析结果落在你的某个根目录内，就会被拒绝。根目录存放数据，永不存放代码。
• 环境是构造出来的，而非继承的，因此像 RIPGREP_CONFIG_PATH 这样的变量无法偷偷引入一个从不出现在参数列表中的辅助程序。
• 用允许列表，绝不用拒绝列表。 拒绝列表只是一份某人想到的 flag 清单。
• 范围包含工作目录，因此不带路径参数的命令会按其运行位置来判定，而不是因为没指定任何东西就通过。

安全性

策略文件、其父目录、你的程序目录以及整个审计日志目录都是受保护位置。默认命令集不包含任何写入操作，因此开箱即用时这些位置都不可达。如果你添加了写入类命令（按名称包括 cp、mv、rm、tee、ln、chmod 以及其他几个），服务会拒绝任何路径参数落在受保护位置上的调用，既按路径匹配，也按文件系统标识匹配。该检查以命令的名称为键，而不是以任意程序可能做什么为依据：不在该列表中的写入类命令不在覆盖范围内，因此只有当你能信任它会写入什么时才添加。

对配置执行 chmod 444 值得作为第二层独立防护。它不是该机制本身：替换文件需要其_目录_的写权限，而非文件本身。

每个请求，无论被允许还是被拒绝，都会记录到仅追加的审计日志中。

已知限制，明确说明而非暗示——见 SECURITY.md：

• 路径检测是启发式的，且会安全失败（fail closed）
• 根目录内的一切都可通过一次递归搜索自由读取
• ask 的强度仅取决于宿主机的批准提示
• 同名命令在不同实现之间，flag 的含义可能不同

通过私密安全公告或 [email protected] 报告漏洞。

从 1.x 迁移

已移除： add_to_whitelist、update_security_level、remove_from_whitelist、approve_command、deny_command、get_pending_commands、get_whitelist。

前三个允许任何客户端将一条被禁止的命令提升为 safe。后三个构成了一套审批工作流，而发起请求的 Agent 可以自行将其抽干。get_whitelist 由 get_policy 取代。

运行时的白名单修改变为由你编辑、服务在启动时读取的配置文件。rm 在 1.x 中是 FORBIDDEN，现在仍然不可用，因此先前能正常工作的东西没有一项停止工作。

开发

npm install && npm run build
npm test          # run it twice; a suite that only passes once is not passing
npm run lint && npm run format:check

设计与规范：openspec/changes/mac-shell-mcp-2-security-redesign/。

许可证

MIT —— 见 LICENSE。