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 find includes -exec/-ok which execute commands; we forbid them.

• GNU/BSD find -delete is 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

Install globally

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:

This interactive script will:

• Create ~/.crush.json if 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:

Manual Setup

If you prefer manual configuration, add the following to your ~/.crush.json:

Verify installation

Usage with Crush

Automatic Setup (Recommended)

Use the setup utility after installation:

Manual Configuration

Add to your ~/.crush.json configuration file:

If you prefer not to install globally, you can specify the full path to the script:

Or use npx:

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

Uninstall