safe-unix-mcp
A stdio MCP server that exposes read-only Unix-like tools to AI agents (Crush).
- Transport: stdio (MCP).
- Host: any MCP client (e.g., Crush).
- OS: Linux/macOS (BSD/GNU differences are handled conservatively).
Why
- POSIX
findincludes-exec/-okwhich execute commands; we forbid them. - GNU/BSD
find -deleteis destructive; also forbidden. - Many coreutils have dangerous flags (e.g.,
sed -i); we block them.
References:
- MCP transports & specification.
- POSIX Shell & Utilities (Open Group).
- GNU Coreutils manual.
Installation
Clone the repository
git clone https://github.com/YOUR_USERNAME/safe-unix-mcp.git
cd safe-unix-mcp
Install globally
npm install -g .
This makes the mcp-safe-unix command available system-wide.
Quick Setup for Crush
After installing globally, run the setup utility to automatically configure your Crush config:
setup-safe-unix
This interactive script will:
- Create
~/.crush.jsonif it doesn't exist - Add the safe-unix MCP server configuration
- Detect and optionally remove potentially unsafe Unix/shell servers
- Update existing safe-unix configuration if already present
Options:
setup-safe-unix --config-path=/custom/path/to/config.json # Use custom config path
setup-safe-unix --force # Skip confirmation prompts
Manual Setup
If you prefer manual configuration, add the following to your ~/.crush.json:
{
"mcpServers": {
"safe-unix": {
"command": "mcp-safe-unix",
"transport": "stdio"
}
}
}
Verify installation
echo '{"jsonrpc":"2.0","id":1,"method":"initialize"}' | mcp-safe-unix
Usage with Crush
Automatic Setup (Recommended)
Use the setup utility after installation:
setup-safe-unix
Manual Configuration
Add to your ~/.crush.json configuration file:
{
"mcpServers": {
"safe-unix": {
"command": "mcp-safe-unix",
"transport": "stdio"
}
}
}
If you prefer not to install globally, you can specify the full path to the script:
{
"mcpServers": {
"safe-unix": {
"command": "node",
"args": ["/path/to/safe-unix-mcp/mcp-safe-unix.js"],
"transport": "stdio"
}
}
}
Or use npx:
{
"mcpServers": {
"safe-unix": {
"command": "npx",
"args": ["-y", "/path/to/safe-unix-mcp"],
"transport": "stdio"
}
}
}
Available Tools
The server exposes the following safe, read-only Unix tools:
- Directory & file listing:
safe_ls,safe_pwd,safe_stat,safe_file - View/paging:
safe_cat,safe_head,safe_tail,safe_less,safe_more - Search & filtering:
safe_grep,safe_awk,safe_sed - Text transforms:
safe_cut,safe_paste,safe_tr,safe_sort,safe_uniq,safe_fmt,safe_fold,safe_column - Counting/checksums:
safe_wc,safe_cksum,safe_sha - Archive inspection:
safe_tar_list,safe_zipinfo,safe_unzip_list - FS usage:
safe_du,safe_df - Process & env:
safe_env,safe_id,safe_uname,safe_date,safe_ps,safe_uptime - Safe find:
safe_find(without-exec,-ok,-delete) - Git (read-only):
safe_git(status, diff, show, log, etc.) - JSON/YAML:
safe_jq,safe_yq - Hex/encoding:
safe_hexdump,safe_xxd,safe_od - Trees:
safe_tree - macOS:
safe_sw_vers
Development
Local testing without global install
# Test with node directly
echo '{"jsonrpc":"2.0","id":1,"method":"initialize"}' | node mcp-safe-unix.js
# Or use npm link for development
npm link
Uninstall
npm uninstall -g safe-unix-mcp