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, * |