https://github.com/kevinwatt/shell-mcp
https://github.com/kevinwatt/shell-mcp
Last synced: 6 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/kevinwatt/shell-mcp
- Owner: kevinwatt
- License: mit
- Created: 2025-02-15T16:23:14.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-02-20T18:14:08.000Z (8 months ago)
- Last Synced: 2025-03-26T16:55:04.829Z (7 months ago)
- Language: TypeScript
- Size: 126 KB
- Stars: 2
- Watchers: 1
- Forks: 2
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- mcp-index - Shell Command Execution Server - Execute shell commands securely with whitelisted options, ensuring controlled and monitored execution for machine learning applications. (Cloud Services)
README
# shell-mcp
> Shell command execution MCP server
[](https://github.com/kevinwatt/shell-mcp)
[](LICENSE)
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
```bash
npm install @kevinwatt/shell-mcp
```
## Configuration with [Dive Desktop](https://github.com/OpenAgentPlatform/Dive)
1. Click "+ Add MCP Server" in Dive Desktop
2. Copy and paste this configuration:
```json
{
"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:
```bash
npx @kevinwatt/shell-mcp
```
## Requirements
- Node.js 18+
- MCP-compatible LLM service
## Development
```bash
# 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, * |