Safe Unix

You can run a safe, read-only set of Unix-like tools through an MCP client using a lightweight stdio server. This server exposes familiar utilities in a guarded way, preventing dangerous operations while enabling automation, analysis, and data processing by AI agents.

How to use

Connect your MCP client to the safe Unix MCP server over stdio. You configure the client to start the server process and route JSON-RPC messages through standard input/output. The server presents a large collection of read-only tools for listing, viewing, searching, transforming, and analyzing file system data and text without executing potentially harmful commands.

Typical usage patterns include feeding the server JSON-RPC requests to run safe commands like listing directories, viewing file contents, or filtering text. Because the server is designed to be read-only and to forbid dangerous options often found in core utilities, you should rely on single-purpose, non-destructive operations and validate results against your workflow. If you need a tool outside the provided set, consider whether you can achieve your goal with a safe combination of available commands.

How to install

Prerequisites you need on your machine:

• Node.js and npm (Node package manager) are required to install and run the MCP server locally.

Follow these concrete steps to install and set up the server.

# 1) Clone the repository
git clone https://github.com/YOUR_USERNAME/safe-unix-mcp.git
cd safe-unix-mcp

# 2) Install globally so the mcp-safe-unix command is available system-wide
npm install -g .

# 3) Optional: run the setup utility to configure your client (Crush) automatically
setup-safe-unix

Additional configuration and notes

Manual configuration for your MCP client (Crush) is supported. You can specify the safe-unix MCP server in your client’s configuration to start the server as a stdio process and connect it via standard input/output.

If you prefer to maintain your own workflow, you can directly add the following configuration snippet to your Crush config file to enable the safe-unix MCP server as a stdio transport.

{
  "mcpServers": {
    "safe-unix": {
      "command": "mcp-safe-unix",
      "transport": "stdio"
    }
  }
}

Security and usage notes

This server intentionally provides read-only access to a curated set of Unix-like tools. It blocks dangerous flags and operations that can delete data or execute external commands. Treat it as a non-destructive data analysis and tooling environment for automated processes.

To ensure smooth operation, keep your client and server updated, and prefer explicit, reproducible tool invocations. Do not rely on destructive behaviors or shell features that can compromise safety.

Available tools

safe_ls

List directory contents in a read-only manner compatible with your automation workflows.

safe_pwd

Print the current working directory without modifying the environment.

safe_stat

Display file or directory status information in a safe, non-destructive way.

safe_file

Identify a file type and basic metadata without executing external commands.

safe_cat

View file contents with safe defaults and paging support.

safe_head

Show the first lines of a file for quick inspection.

safe_tail

Show the last lines of a file for quick inspection.

safe_less

Paged view of file contents for large outputs.

safe_grep

Search text with safe patterns and restricted execution context.

safe_awk

Process text data with read-only pattern/action rules.

safe_sed

Apply non-destructive text transformations under strict safety rules.

safe_cut

Extract sections from lines of input safely.

safe_paste

Merge lines from multiple inputs in a read-only fashion.

safe_tr

Translate or replace character sets in text safely.

safe_sort

Sort lines of text without modifying source data.

safe_uniq

Filter repeated lines to produce unique outputs.

safe_fmt

Format text into a clean, consistent layout.

safe_fold

Wrap long lines safely for readable output.

safe_column

Align text into columns for readable displays.

safe_wc

Count words, lines, and bytes in input data.

safe_cksum

Compute checksums for data integrity checks.

safe_sha

Compute SHA-based digests for data integrity.

safe_tar_list

Inspect tar archives contents without extraction.

safe_zipinfo

Inspect ZIP archive contents safely.

safe_unzip_list

List files inside ZIP archives without extraction.

safe_du

Estimate file space usage in a read-only manner.

safe_df

Report filesystem disk space usage.

safe_env

Inspect environment variables in a non-destructive way.

safe_id

Display user and group identity information.

safe_uname

Display system information in a read-only way.

safe_date

Format and display dates without altering the system.

safe_ps

Report active processes in a safe, non-intrusive way.

safe_uptime

Show how long the system has been running.

safe_find

Search for files with basic queries; excludes -exec, -ok, -delete to remain safe.

safe_git

Read-only Git state, diffs, logs, and basic status information.

safe_jq

Query and transform JSON data safely.

safe_yq

Query and transform YAML data safely.

safe_hexdump

Display binary data as hexadecimal for inspection.

safe_xxd

Hex dump of data with readable formatting.

safe_od

Dump output in various formats for data inspection.

safe_tree

Display directory tree structure without modification.

safe_sw_vers

Report macOS version information in a read-only manner.