Reference MCP server giving coding agents shell access done right: foreground commands with timeouts, background processes with PIDs, live output inspection and graceful termination
Shell-mcp has 4 tools with complete input schemas and descriptions, but significant quality gaps limit production readiness. Tool naming is inconsistent ('execut_command' appears to be a typo for 'execute_command'). Descriptions are verbose (200-400 chars) but lack structured guidance on when to use each tool vs alternatives. Parameters are well-typed with defaults, but descriptions don't specify constraints (e.g., timeout range, cwd validation). Output schemas are not formally documented, responses are free-text strings rather than structured objects. Error handling is minimal: no recovery guidance, no categorization of retryable vs fatal errors. The tool set lacks composition patterns: no batch operations, no pagination for multi-item results. Security concerns: command execution is inherently destructive and requires strict input validation not visible in the provided code.
Execute a shell command on the user's machine. Args: command: The shell command to execute (e.g. "ls -la", "npm install", "python script.py"). cwd: Absolute path to the working directory where the command will run. run_in_background: If True, the command runs as a background process and returns its PID immediately instead of waiting for completion. Use this for long-running processes like servers, file watchers, or builds. You can then poll output with `read_output` and stop it with `kill_process`. timeout: Maximum seconds to wait for a foreground command to finish (default 120). Ignored when run_in_background is True. The process is killed if it exceeds this limit. Returns: For foreground commands: a string with stdout and stderr. For background commands: the integer PID of the spawned process.
Detect the host operating system. Call this first to determine which shell syntax and commands are available (e.g. bash on Linux/Darwin vs cmd/powershell on Windows). Returns: The OS name as a string: "Linux", "Darwin" (macOS), or "Windows".
Terminate a background process that was previously started with `execut_command(run_in_background=True)`. Args: pid: The process ID returned by `execut_command` when the background process was started. Returns: A confirmation message that the process was killed, or an error if the PID is unknown.
Read information about a running background process. Uses OS-level tools (lsof on Unix, tasklist on Windows) to inspect the process and return its current state, including open file descriptors and resource usage. Args: pid: The process ID returned by `execut_command` when the background process was started. last: Maximum number of lines to return from the output (default 300). Returns: A string containing process information, or an error if the PID is not found.
Tool name 'execut_command' appears to be a typo; should be 'execute_command'. Misspelled names confuse LLMs and violate verb_noun naming convention.
No output schemas documented. All tools return free-text strings instead of structured objects. LLMs cannot parse results reliably or chain tools without guessing field names.
Error handling lacks recovery guidance. Errors are bare strings ('Process not found', 'Command timed out') with no actionable next steps for the LLM.
Parameter descriptions lack constraints. 'timeout' has no range (e.g., 1-3600s), 'cwd' has no validation rules, 'last' has no bounds. LLMs will pass invalid values.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 55 | <=2025-11-25 | v2 |
No confirmation or dry-run pattern for destructive operations. 'execut_command' can delete files or corrupt systems with no safety gate.