shell-mcp

Shell command execution MCP server

An MCP server implementation that provides secure shell command execution capabilities for LLMs.

Features

• Secure Execution: Whitelisted commands and arguments only
• Resource Control: Memory and CPU usage monitoring
• Timeout Control: Automatic termination of long-running commands
• Size Limits: Output size restrictions for safety
• MCP Integration: Works with Claude and other MCP-compatible LLMs

Installation

npm install @kevinwatt/shell-mcp

Configuration with Dive Desktop

1. Click "+ Add MCP Server" in Dive Desktop
2. Copy and paste this configuration:

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

Tool Documentation

• shell_ls, shell_pwd, shell_df, etc.
  • Execute whitelisted shell commands
  • Inputs:
    • command (string, required): Command to execute
    • args (array, optional): Command arguments
    • timeout (number, optional): Execution timeout in ms

Usage Examples

Ask your LLM to:

"Show current directory using shell_pwd"
"List files using shell_ls with -l argument"
"Check disk usage using shell_df with -h argument"

Manual Start

If needed, start the server manually:

npx @kevinwatt/shell-mcp

Requirements

• Node.js 18+
• MCP-compatible LLM service

Development

# Install dependencies
npm install

# Watch mode
npm run watch

# Run tests
npm test

# Lint
npm run lint

License

MIT © Dewei Yen

Keywords

• mcp
• shell
• command
• claude
• llm
• automation

Available Commands

The following shell commands are available:

Command	Description	Allowed Arguments
ls	List directory contents	-l, -a, -h, -R, --help, *
cat	Concatenate and display file contents	-n, -b, --help, *
pwd	Show current working directory	None
df	Show disk usage	-h, -T, --help
echo	Display text	Any text
ps	Show process status	-e, -f, -u, --help
free	Show memory usage	-h, -m, -g, --help
uptime	Show system uptime	None
date	Show system date and time	+%Y-%m-%d, +%H:%M:%S, --help
grep	Search text patterns in files	-i, -v, -n, -r, -l, --color, *
w	Show who is logged on and what they are doing	-h, -s, --no-header, --help
whois	Query WHOIS domain registration information	-H, *
find	Search for files in a directory hierarchy	-name, -type, -size, -mtime, *
netstat	Network connection information	-a, -n, -t, -u, -l, -p, --help
lspci	List PCI devices	-v, -k, -mm, -nn, --help
lsusb	List USB devices	-v, -t, -d, -s, --help
dig	DNS lookup utility	+short, +trace, +dnssec, @*, *
nslookup	Query DNS records	-type=, -query=, *
ip	Show network devices and interfaces	addr, link, route, neigh, -br, *
whereis	Locate binary, source and manual files	-b, -m, -s, *