Shell

You can securely run a restricted set of shell commands from an MCP client using this server. It enforces whitelisting, monitors resource usage, and enforces timeouts and output size limits to keep interactions safe while enabling practical automation with LLMs.

How to use

You interact with the server through an MCP client that supports the standard MCP protocol. The client can request execution of whitelisted shell commands and receive controlled results. Typical workflows include asking your LLM to run commands like listing files, showing the current directory, or checking disk usage. For each request you specify the command you want to run and any arguments; the server enforces allowed commands and arguments, applies a timeout, and limits the size of the output.

How to install

# Prerequisites
- Node.js 18+

# Install the MCP server package
npm install @kevinwatt/shell-mcp

# Start the server locally (stdio configuration via npx)
npx @kevinwatt/shell-mcp

Additional configuration and usage notes

Configure your MCP client to connect to this server using a local stdio setup. The server is started with a simple command and does not require a remote URL. If you are using a desktop client that accepts an MCP server configuration, you can provide the following setup to enable execution through the client.

{
  "mcpServers": {
    "shell_mcp": {
      "command": "npx",
      "args": ["@kevinwatt/shell-mcp"]
    }
  }
}

Security and behavior details

This server executes only whitelisted commands and arguments. It monitors memory and CPU usage, enforces execution timeouts, and imposes output size limits to maintain safety during automated interactions. When you configure or use the server, ensure that the client passes only permitted inputs and respects the documented command set.

Examples of supported tools and commands

The server exposes a set of whitelisted shell commands. Examples include directory listing, file viewing, process inspection, and system information. Each command is constrained to allowed arguments to prevent unsafe operations. For instance, you can list files, print the current directory, or check disk usage using the following command patterns via the MCP client.

Troubleshooting

If you encounter issues starting the server, ensure Node.js 18+ is installed. Then reinstall and retry starting with the standard start command shown above. If outputs are unexpectedly large or commands timeout, verify that you are using allowed arguments and consider reducing the scope of requested operations.

Notes on available commands

The server supports a range of common shell utilities. Each command is invoked with whitelisted arguments only, as described in the tool list that accompanies the server. If a command or argument is not whitelisted, the MCP client should refrain from requesting it.

Examples of common requests

- Show current directory: { command: "shell_pwd" }
- List files with details: { command: "shell_ls", args: ["-l"] }
- Check disk usage: { command: "shell_df", args: ["-h"] }

Available tools

shell_ls

Execute whitelisted ls commands to list directory contents with optional flags like -l, -a, -h, -R.

shell_pwd

Show the current working directory.

shell_df

Show disk usage with options like -h and -T.

shell_cat

Display file contents with optional line numbering options like -n or -b.

shell_echo

Display provided text.

shell_ps

Show process status with commonly used flags like -e and -f.

shell_free

Show memory usage with options like -h, -m, or -g.

shell_uptime

Show system uptime.

shell_date

Show system date and time with formatting options such as +%Y-%m-%d or +%H:%M:%S.

shell_grep

Search text patterns in files with typical options like -i, -n, -r, -l.

shell_w

Show who is logged on and what they are doing.

shell_whois

Query WHOIS domain registration information.

shell_find

Search for files in a directory hierarchy using common predicates such as -name or -type.

shell_netstat

Network connection information with flags like -a, -n, -t, -u.

shell_lspci

List PCI devices with options like -v or -k.

shell_lsusb

List USB devices with various display options.

shell_dig

Perform DNS lookups with options like +short or +trace.

shell_nslookup

Query DNS records with options like -type or -query.

shell_ip

Show network devices and interfaces with subcommands like addr or link.

shell_whereis

Locate binaries, sources, and manuals with options -b, -m, -s.