shell_execute
Execute shell commands with bounded output retention, adaptive execution, and pipeline support for managing long-running processes.
Instructions
Execute shell commands with bounded output retention. When output_id is present, read_execution_output returns the retained output; output_truncated=true means data beyond max_output_size was not retained. Supports adaptive execution mode and input_output_id pipeline operations. NOTE: This is MCP Shell Server tool - do NOT use VS Code internal run_in_terminal parameters like "explanation" or "isBackground".
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | Shell command to execute (e.g., "ls -la", "npm install", "python script.py"). Restrictive mode permits full shell syntax only inside its required Bubblewrap profile; other executable modes are not OS-confined. NOTE: This is MCP Shell Server - do NOT use VS Code internal run_in_terminal parameters like "explanation". | |
| comment | No | Optional comment from the LLM client explaining the intent or context behind this command execution. This helps the command evaluator understand the broader context, but will be treated as advisory only and not blindly trusted. | |
| input_data | No | Standard input data to provide to the command. Useful for commands that read from stdin. | |
| session_id | No | Session ID for grouping related command executions. Used for process management and filtering in process_list. | |
| capture_stderr | No | Whether to capture standard error output in addition to stdout. When false, stderr is discarded. | |
| execution_mode | No | How the command should be executed: "foreground" (wait for completion), "background" (run async), "detached" (fire-and-forget), "adaptive" (start foreground, switch to background for long-running commands) | adaptive |
| terminal_shell | No | Shell type for the new terminal (bash, zsh, fish, cmd, powershell). Only used when create_terminal is true. | |
| create_terminal | No | Create a new interactive terminal session instead of running command directly. Restrictive mode rejects this route with SANDBOX_TERMINAL_UNAVAILABLE. | |
| input_output_id | No | Output ID from previous command execution to use as input. Alternative to input_data for pipeline operations. | |
| max_output_size | No | Maximum output size in bytes (1KB-100MB). Output will be truncated if it exceeds this limit. Default: 5MB. | |
| timeout_seconds | No | Global timeout (1-3600s). Default: 60s. Per execution_mode (effective limits before execution starts): • foreground: Schema allows 1-3600s, but the default security policy caps runs at 300s. Increase MCP_SHELL_MAX_EXECUTION_TIME in trusted startup configuration when a larger cap is required. • background: 1-3600s. Intended for >300s runs; still subject to the same security cap (300s by default) unless raised. • detached: 1-3600s. Shares the security cap behavior with background. • adaptive: 1-3600s total cap. The initial foreground phase also respects foreground_timeout_seconds (≤300s) and the security cap. Guidance: For long-running tasks (>300s), raise max_execution_time or use background/adaptive modes. | |
| working_directory | No | Directory where the command should be executed. If not specified, uses the default working directory set by shell_set_default_workdir or the initial server directory. | |
| force_user_confirm | No | Force user confirmation regardless of LLM evaluation result. Use this to test ELICITATION functionality or when direct user confirmation is required even if the evaluator would allow the command. | |
| terminal_dimensions | No | Terminal dimensions in characters (width x height). Only used when create_terminal is true. Default: 120x30. | |
| environment_variables | No | Environment variables to set for direct host execution. Restrictive mode rejects request environment overrides with SANDBOX_ENV_UNSUPPORTED. | |
| return_partial_on_timeout | No | When timeout occurs, return partial output collected so far instead of an error. Useful for monitoring long-running commands. | |
| foreground_timeout_seconds | No | Initial foreground window for adaptive mode (1-300s). Behavior by execution_mode: • adaptive: Duration to remain in foreground before automatically switching to background if the command is still running. Must be ≤ timeout_seconds. • foreground: Does not trigger background switching (value is effectively unused for switching). Use background/adaptive for >300s scenarios. • background/detached: Ignored. |