terminal
Execute shell commands to run scripts, manage files, and automate system tasks directly from an MCP client, returning stdout, stderr, and exit codes.
Instructions
Run a shell command and return its output.
Returns a single string containing stdout, and stderr when present. Non-zero exit codes are reported at the end of the output so the caller can detect failures without parsing exit status separately.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | The shell command to execute. Runs via /bin/sh -c on Unix or cmd /c on Windows. Pipes, redirects, and shell built-ins are supported. Commands time out after 30 seconds. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- server.py:13-55 (handler)The terminal function is the handler for the 'terminal' tool, executing shell commands via subprocess.run.
def terminal( command: Annotated[ str, Field( description=( "The shell command to execute. Runs via /bin/sh -c on Unix or cmd /c " "on Windows. Pipes, redirects, and shell built-ins are supported. " "Commands time out after 30 seconds." ) ), ], ) -> str: """Run a shell command and return its output. Returns a single string containing stdout, and stderr when present. Non-zero exit codes are reported at the end of the output so the caller can detect failures without parsing exit status separately. """ try: result = subprocess.run( command, shell=True, capture_output=True, text=True, timeout=30, ) except subprocess.TimeoutExpired: return "Error: command timed out after 30 seconds." except Exception as exc: # noqa: BLE001 return f"Error: failed to execute command — {exc}" parts: list[str] = [] if result.stdout: parts.append(result.stdout.rstrip()) if result.stderr: parts.append(f"STDERR:\n{result.stderr.rstrip()}") if result.returncode != 0: parts.append(f"Exit code: {result.returncode}") return "\n".join(parts) if parts else "(no output)" - server.py:12-12 (registration)Registration of the 'terminal' tool using the FastMCP decorator.
@mcp.tool()