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

This server cannot be installed

-

security - not tested

F

license - not found

-

quality - not tested

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Provides read-only access to Unix/Linux command-line tools for AI agents, blocking dangerous operations like file deletion, modification, and command execution while enabling safe file inspection, searching, and system information gathering.

Safe Unix MCP