execute_command
Execute terminal commands on macOS securely via the Mac Shell MCP Server, using built-in whitelisting and approval mechanisms for controlled access.
Instructions
Execute a shell command on macOS
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | Command arguments | |
| command | Yes | The command to execute |
Input Schema (JSON Schema)
{
"properties": {
"args": {
"description": "Command arguments",
"items": {
"type": "string"
},
"type": "array"
},
"command": {
"description": "The command to execute",
"type": "string"
}
},
"required": [
"command"
],
"type": "object"
}
Implementation Reference
- src/index.ts:90-110 (registration)Registration of the 'execute_command' tool in the MCP server's listTools handler, defining its name, description, and input 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'], }, },
- src/index.ts:268-305 (handler)MCP tool handler for 'execute_command': validates input parameters using Zod schema and delegates to CommandService for execution, returning formatted MCP response.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:269-272 (schema)Zod schema for validating 'execute_command' tool arguments within the handler.const schema = z.object({ command: z.string(), args: z.array(z.string()).optional(), });
- src/services/command-service.ts:308-348 (handler)Core command execution logic: validates against whitelist, handles security levels (safe/approval/forbidden), executes safe commands directly or queues others for approval 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; } }