Mac Shell MCP Server
An MCP server that lets an AI client run a small, fixed set of read-only shell commands, confined to directories you nominate.
接入你的智能体
從發布者安裝。不是 PlugMCP 端點。
遠端 URL 還是本機指令? 兩種安裝方式的差異
來自發布者
An MCP server that lets an AI client run a small, fixed set of read-only shell commands, confined to directories you nominate.
An MCP (Model Context Protocol) server for executing macOS terminal commands with ZSH shell. This server provides a secure way to execute shell commands with built-in whitelisting and approval mechanisms.
It is built around one idea: the agent cannot widen its own authority. There is no tool that edits the policy, no approval queue the agent can drain, and no shell to interpret its arguments.
Upgrading from 1.x? 2.0.0 is a breaking change. Seven tools were removed and the authorization model was replaced. See Migrating from 1.x. 1.x contained two vulnerabilities reported by four independent researchers; see the security advisories.
ls pwd echo cat head tail wc grep
Each is restricted to an allowlist of flags. None of them can write a file, execute another program, or read configuration from the environment.
find, git, rm and every interpreter are absent by default. You can add any of them, and should know why they are not there:
find -fprintf writes attacker-chosen content to an attacker-chosen path, while find is naturally classified read-onlygit executes commands from a repository's own .git/config, and no environment variable disables thatpython, perl, awk, node, osascript, …) take inline code as an argumentnpm install -g @the_cfdude/mac-shell-mcp
Then create a policy:
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
Add to your MCP client:
{
"mcpServers": {
"mac-shell": { "command": "npx", "args": ["-y", "@the_cfdude/mac-shell-mcp"] }
}
}
A fresh install with no roots configured refuses everything — deliberately. Each refusal names the permitted commands and where configuration lives, so the first failure tells you what to do.
Policy is found in this order, first match wins, never merged:
$MAC_SHELL_MCP_CONFIG — an explicit path~/.mac-shell-mcp/config.jsonMAC_SHELL_ROOTS, MAC_SHELL_COMMANDS)Policy is never read from the working directory. A cloned repository must not be able to supply the policy governing the agent that opens it.
{
"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 is allow, ask, or deny. ask requires a client offering MCP elicitation — the only capability that means a human can be asked. Where it is absent, ask becomes deny, never allow.
Authorization is effect × scope, computed per call. grep inside your project is free; the same grep against ~/.aws is not. The command name alone never decides.
execFile is never given a shell option, so arguments reach the OS uninterpreted. Nothing evaluates ;, $(), or backticks — which is also why filenames with spaces, parentheses and brackets work normally.RIPGREP_CONFIG_PATH cannot smuggle in a helper program that never appears in the argument list.The policy file, its parent directories, your program directories, and the whole audit log directory are protected locations. The default command set contains nothing that writes, so none of them is reachable out of the box. If you add a command that writes (cp, mv, rm, tee, ln, chmod, and a few others, by name), the server refuses any call whose path arguments land on a protected location, matched by filesystem identity as well as by path. That check is keyed on the command's name, not on what an arbitrary program might do: a writing command outside that list is not covered, so add one only if you trust what it can write.
chmod 444 on your config is worth doing as a second, independent layer. It is not the mechanism: replacing a file needs write permission on its directory, not the file.
Every request, permitted or refused, is recorded to an append-only audit log.
Known limits, stated rather than implied — see SECURITY.md:
ask is only as strong as the host's approval promptReport vulnerabilities via private advisory or [email protected].
Removed: add_to_whitelist, update_security_level, remove_from_whitelist, approve_command, deny_command, get_pending_commands, get_whitelist.
The first three let any client promote a forbidden command to safe. The next three formed an approval workflow the requesting agent could drain by itself. get_whitelist is replaced by get_policy.
Runtime whitelist edits become a config file you edit and the server reads at startup. rm was FORBIDDEN in 1.x and remains unavailable, so nothing that worked before stops working.
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
Design and specifications: openspec/changes/mac-shell-mcp-2-security-redesign/.
MIT — see LICENSE.
An MCP (Model Context Protocol) server for executing macOS terminal commands with ZSH shell. This server provides a secure way to execute shell commands with built-in whitelisting and approval mechani
總覽
An MCP (Model Context Protocol) server for executing macOS terminal commands with ZSH shell. This server provides a secure way to execute shell commands with built-in whitelisting and approval mechanisms.
工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
Mac Shell 透過 stdio 在本機執行。
上次檢查時間:2026-11-05。 An MCP (Model Context Protocol) server for executing macOS terminal commands with ZSH shell. This server provides a secure way to execute shell commands with built-in whitelisting and approval mechanisms.