A secure MCP server for executing whitelisted shell commands with resource and timeout controls, designed for integration with Claude and other MCP-compatible LLMs.
Shell command execution MCP server
An MCP server implementation that provides secure shell command execution capabilities for LLMs.
npm install @kevinwatt/shell-mcp{
"mcpServers": {
"shell": {
"command": "npx",
"args": [
"-y",
"@kevinwatt/shell-mcp"
]
}
}
}command (string, required): Command to executeargs (array, optional): Command argumentstimeout (number, optional): Execution timeout in msAsk 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"If needed, start the server manually:
npx @kevinwatt/shell-mcp# Install dependencies
npm install
# Watch mode
npm run watch
# Run tests
npm test
# Lint
npm run lintMIT © Dewei Yen
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, * |
[
{
"description": "List directory contents",
"inputSchema": {
"properties": {
"args": {
"description": "Command arguments",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"name": "shell_ls"
},
{
"description": "Concatenate and display file contents",
"inputSchema": {
"properties": {
"args": {
"description": "Command arguments",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"name": "shell_cat"
},
{
"description": "Show current working directory",
"inputSchema": {
"properties": {
"args": {
"description": "Command arguments",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"name": "shell_pwd"
},
{
"description": "Show disk usage",
"inputSchema": {
"properties": {
"args": {
"description": "Command arguments",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"name": "shell_df"
},
{
"description": "Display text",
"inputSchema": {
"properties": {
"args": {
"description": "Command arguments",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"name": "shell_echo"
},
{
"description": "Show process status",
"inputSchema": {
"properties": {
"args": {
"description": "Command arguments",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"name": "shell_ps"
},
{
"description": "Show memory usage",
"inputSchema": {
"properties": {
"args": {
"description": "Command arguments",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"name": "shell_free"
},
{
"description": "Show system uptime",
"inputSchema": {
"properties": {
"args": {
"description": "Command arguments",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"name": "shell_uptime"
},
{
"description": "Show system date and time",
"inputSchema": {
"properties": {
"args": {
"description": "Command arguments",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"name": "shell_date"
},
{
"description": "Search text patterns in files",
"inputSchema": {
"properties": {
"args": {
"description": "Command arguments",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"name": "shell_grep"
},
{
"description": "Show who is logged on and what they are doing",
"inputSchema": {
"properties": {
"args": {
"description": "Command arguments",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"name": "shell_w"
},
{
"description": "Query WHOIS domain registration information",
"inputSchema": {
"properties": {
"args": {
"description": "Command arguments",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"name": "shell_whois"
},
{
"description": "Search for files in a directory hierarchy",
"inputSchema": {
"properties": {
"args": {
"description": "Command arguments",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"name": "shell_find"
},
{
"description": "Network connection information",
"inputSchema": {
"properties": {
"args": {
"description": "Command arguments",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"name": "shell_netstat"
},
{
"description": "List PCI devices",
"inputSchema": {
"properties": {
"args": {
"description": "Command arguments",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"name": "shell_lspci"
},
{
"description": "List USB devices",
"inputSchema": {
"properties": {
"args": {
"description": "Command arguments",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"name": "shell_lsusb"
},
{
"description": "DNS lookup utility",
"inputSchema": {
"properties": {
"args": {
"description": "Command arguments",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"name": "shell_dig"
},
{
"description": "Query DNS records",
"inputSchema": {
"properties": {
"args": {
"description": "Command arguments",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"name": "shell_nslookup"
},
{
"description": "Show / manipulate routing, network devices, interfaces and tunnels",
"inputSchema": {
"properties": {
"args": {
"description": "Command arguments",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"name": "shell_ip"
},
{
"description": "Locate the binary, source, and manual page files for a command",
"inputSchema": {
"properties": {
"args": {
"description": "Command arguments",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"name": "shell_whereis"
}
]