press_key
Destructive
Simulate keyboard presses with modifiers like cmd, ctrl, shift, and alt for macOS automation. Use key combos such as "cmd+c" or "ctrl+shift+F5" to automate tasks.
Instructions
Simulate a key press with optional modifiers. Accepts a key combo string like "cmd+c", "ctrl+shift+F5", or "Return". Modifiers: cmd, ctrl, shift, opt/alt.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Key combo string. Examples: "Return", "cmd+c", "ctrl+shift+F5", "alt+Tab". |
Implementation Reference
- src/tools/keyboard.ts:159-221 (handler)The handler function `handlePressKey` executes the tool logic by parsing the input, validating the keys/modifiers, and executing an AppleScript command to simulate the key press on macOS.
async function handlePressKey( args: Record<string, unknown>, ): Promise<CallToolResult> { const parsed = PressKeyInputSchema.parse(args); const parts = parsed.key.split("+"); const baseKeyName = parts[parts.length - 1]; const modifierNames = parts.slice(0, -1); // Look up the base key code (case-insensitive) const code = KEY_CODES_LOWER[baseKeyName.toLowerCase()]; if (code === undefined) { return { isError: true, content: [ { type: "text" as const, text: `Unknown key name: "${baseKeyName}". Valid key names include: ${KEY_NAME_EXAMPLES.join(", ")}`, }, ], }; } // Build AppleScript modifier clause const asModifiers: string[] = []; for (const mod of modifierNames) { const canonical = MODIFIER_ALIASES[mod.toLowerCase()]; if (canonical === undefined) { return { isError: true, content: [ { type: "text" as const, text: `Unknown modifier: "${mod}". Valid modifiers: cmd, ctrl, shift, opt (or alt).`, }, ], }; } asModifiers.push(`${canonical} down`); } // Build and execute AppleScript const script = asModifiers.length > 0 ? `tell application "System Events" to key code ${code} using {${asModifiers.join(", ")}}` : `tell application "System Events" to key code ${code}`; await execFileAsync("osascript", ["-e", script], { timeout: APPLESCRIPT_TIMEOUT_MS, }); return { content: [ { type: "text" as const, text: JSON.stringify({ success: true, key: parsed.key, }), }, ], }; } - src/tools/keyboard.ts:61-69 (schema)The Zod schema `PressKeyInputSchema` defines the expected input format for the `press_key` tool.
const PressKeyInputSchema = z.object({ key: z .string() .min(1) .max(200) .describe( 'Key combo string. Examples: "Return", "cmd+c", "ctrl+shift+F5", "alt+Tab".', ), }); - src/tools/keyboard.ts:84-94 (registration)Registration of the `press_key` tool within the `keyboardToolDefinitions` array.
{ name: "press_key", description: 'Simulate a key press with optional modifiers. Accepts a key combo string like "cmd+c", "ctrl+shift+F5", or "Return". Modifiers: cmd, ctrl, shift, opt/alt.', inputSchema: zodToToolInputSchema(PressKeyInputSchema), annotations: { readOnlyHint: false, destructiveHint: true, }, }, ];