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

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.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:

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