execute_command
Execute macOS terminal commands securely with built-in whitelisting and approval mechanisms for controlled shell operations.
Instructions
Execute a shell command on macOS
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | The command to execute | |
| args | No | Command arguments |
Implementation Reference
- src/index.ts:268-305 (handler)MCP tool handler for 'execute_command': validates input with Zod, delegates to CommandService.executeCommand, formats stdout/stderr response or error.
private async handleExecuteCommand(args: unknown) { const schema = z.object({ command: z.string(), args: z.array(z.string()).optional(), }); const { command, args: commandArgs = [] } = schema.parse(args); try { const result = await this.commandService.executeCommand(command, commandArgs); return { content: [ { type: 'text', text: result.stdout, }, { type: 'text', text: result.stderr ? `Error output: ${result.stderr}` : '', }, ], }; } catch (error) { if (error instanceof Error) { return { content: [ { type: 'text', text: `Command execution failed: ${error.message}`, }, ], isError: true, }; } throw error; } } - src/index.ts:93-109 (schema)Input schema definition for 'execute_command' tool as provided in ListTools response.
inputSchema: { type: 'object', properties: { command: { type: 'string', description: 'The command to execute', }, args: { type: 'array', items: { type: 'string', }, description: 'Command arguments', }, }, required: ['command'], }, - src/index.ts:90-110 (registration)Registration of 'execute_command' tool in the ListTools handler, including name, description, and schema.
{ name: 'execute_command', description: 'Execute a shell command on macOS', inputSchema: { type: 'object', properties: { command: { type: 'string', description: 'The command to execute', }, args: { type: 'array', items: { type: 'string', }, description: 'Command arguments', }, }, required: ['command'], }, }, - Core helper method implementing command execution logic: whitelist validation, approval queuing for risky commands, direct execution for safe ones using child_process.execFile.
public async executeCommand( command: string, args: string[] = [], options: { timeout?: number; requestedBy?: string; } = {}, ): Promise<CommandResult> { const securityLevel = this.validateCommand(command, args); // If command is not whitelisted, reject if (securityLevel === null) { throw new Error(`Command not whitelisted: ${command}`); } // If command is forbidden, reject if (securityLevel === CommandSecurityLevel.FORBIDDEN) { throw new Error(`Command is forbidden: ${command}`); } // If command requires approval, add to pending queue if (securityLevel === CommandSecurityLevel.REQUIRES_APPROVAL) { return this.queueCommandForApproval(command, args, options.requestedBy); } // For safe commands, execute immediately try { const timeout = options.timeout || this.defaultTimeout; const { stdout, stderr } = await execFileAsync(command, args, { timeout, shell: this.shell, }); return { stdout, stderr }; } catch (error) { if (error instanceof Error) { throw new Error(`Command execution failed: ${error.message}`); } throw error; } }