Mac ShellSAFE
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.
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
[](https://github.com/cfdude/mac-shell-mcp/actions/workflows/ci.yml) [](https://github.com/cfdude/mac-shell-mcp/actions/workflows/security.yml)
An MCP server that lets an AI client run a small, fixed set of read-only shell commands, confined to directories you nominate.
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.
What it does
Default commands
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
735f288b5bc9OBSERVED · 2026-10-09Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control.
claude mcp add mac-shell-mcp -- npx -y @the_cfdude/[email protected]
{
"mcpServers": {
"mac-shell-mcp": {
"command": "npx",
"args": [
"-y",
"@the_cfdude/[email protected]"
]
}
}
}Exposed tools (5)
1 read · 4 write · 0 destructive.
| Tool | Risk | Description |
|---|---|---|
execute_command | write | Run a permitted command confined to the configured roots. Reads and writes inside a root; refuses anything reaching outside. |
execute_external_command | write | Run a permitted command against paths OUTSIDE the configured roots. Requires interactive approval; refused where the client cannot ask a human. |
execute_pipeline | write | Compose read-only commands, wiring stdout to stdin in process. Every stage is authorized independently and confined to the roots. |
get_policy | read | Report the effective policy: permitted commands with effects, permissions and argument shapes, plus the configured roots. |
suggest_policy_config | write | Summarize recorded usage into configuration a human may apply. Cannot apply it; the policy file is protected. |
Trust audit
SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | PASS |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | PASS |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- none-observed
- Network
- none-observed
- Shell
- none-observed
- Dependencies
- not all pinned
- Secrets in source
- none-found
Findings (12)
mac-shell-mcp-1.0.4.tgz
.mac-shell-mcp.sample.json
.prettierignore
.prettierrc.json
.openspec.yaml
zod, @types/jest, @types/node, @typescript-eslint/eslint-plugin, @typescript-eslint/parser, eslint, eslint-config-prettier, eslint-plugin-prettier
3. **Never run the server with elevated privileges** (e.g., sudo)
- **Commands run with the full permissions of the user running the server.** There is no sandbox.
Underneath both sits a design error: a static command-name allowlist cannot express the real risk. `grep` is nominally read-only and `grep -r AKIA ~/.aws` exfiltrates credentials, while `mkdir ./build
- **WHEN** a pipeline requests `cat ~/.aws/credentials` followed by `grep AKIA`, where both stages are read-effect
- [ ] 6.0b Write a failing test asserting the request's **working directory is a scope input for every tool**, and that a request carrying NO path-shaped argument is classified by its cwd rather than
- [ ] 6.4 Write failing tests asserting `execute_pipeline` authorizes every stage **completely** — program, effect, scope, argument rules and permission — so that a permitted read followed by a **writ
Gates applied: no_behavioural_pass.
735f288b5bc9full audit observations/trust-audit/mcp-server/cfdude__mac-shell.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-09 | 735f288b5bc9 | SAFE | B | 89 | first audit |
Questions
What is the Mac Shell MCP server?
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.
What tools does Mac Shell expose?
5 in total: 1 read-only, 4 that write, and 0 that can delete or overwrite. Every one is listed on this page with its risk.
Is Mac Shell safe to connect to an agent?
The audit found nothing in the source that contradicts what it says it does, and graded it B (89/100). Grade A is held back for packages that have also passed a sandboxed behavioural run, which is why a clean server reads B.
What credentials does Mac Shell need?
No credential environment variables were found in its source, so it appears to need none.
How does Mac Shell run?
It speaks stdio and streamable-http, so it runs as a local process your client starts. It is published on npm as @the_cfdude/mac-shell-mcp at 2.0.1.
How current is this page?
The grade is for one exact copy of the source (735f288b5bc9), read on 2026-10-09. The repository is watched and re-audited when it changes.