remote_macos_open_application

Open or activate macOS applications remotely using app names, paths, or bundle IDs, returning the process ID for subsequent control operations.

Instructions

Opens/activates an application and returns its PID for further interactions.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`identifier`	Yes	REQUIRED. App name, path, or bundle ID.

Implementation Reference

src/action_handlers.py:486-557 (handler)

Core handler function that executes the tool: connects to remote macOS via VNC, simulates Cmd+Space to open Spotlight, types the application identifier, and presses Enter to launch it.

def handle_remote_macos_open_application(arguments: dict[str, Any]) -> List[types.TextContent]:
    """
    Opens or activates an application on the remote MacOS machine using VNC.

    Args:
        arguments: Dictionary containing:
            - identifier: App name, path, or bundle ID

    Returns:
        List containing a TextContent with the result
    """
    # Use environment variables
    host = MACOS_HOST
    port = MACOS_PORT
    password = MACOS_PASSWORD
    username = MACOS_USERNAME
    encryption = VNC_ENCRYPTION

    identifier = arguments.get("identifier")
    if not identifier:
        raise ValueError("identifier is required")

    start_time = time.time()

    # Initialize VNC client
    vnc = VNCClient(host=host, port=port, password=password, username=username, encryption=encryption)

    # Connect to remote MacOs machine
    success, error_message = vnc.connect()
    if not success:
        error_msg = f"Failed to connect to remote MacOs machine at {host}:{port}. {error_message}"
        return [types.TextContent(type="text", text=error_msg)]

    try:
        # Send Command+Space to open Spotlight
        cmd_key = 0xffeb  # Command key
        space_key = 0x20  # Space key

        # Press Command+Space
        vnc.send_key_event(cmd_key, True)
        vnc.send_key_event(space_key, True)

        # Release Command+Space
        vnc.send_key_event(space_key, False)
        vnc.send_key_event(cmd_key, False)

        # Small delay to let Spotlight open
        time.sleep(0.5)

        # Type the application name
        vnc.send_text(identifier)

        # Small delay to let Spotlight find the app
        time.sleep(0.5)

        # Press Enter to launch
        enter_key = 0xff0d
        vnc.send_key_event(enter_key, True)
        vnc.send_key_event(enter_key, False)

        end_time = time.time()
        processing_time = round(end_time - start_time, 3)

        return [types.TextContent(
            type="text",
            text=f"Launched application: {identifier}\nProcessing time: {processing_time}s"
        )]

    finally:
        # Close VNC connection
        vnc.close()

src/mcp_remote_macos_use/server.py:218-231 (schema)

Tool schema definition including input schema requiring 'identifier' string.

types.Tool(
    name="remote_macos_open_application",
    description="Opens/activates an application and returns its PID for further interactions.",
    inputSchema={
        "type": "object",
        "properties": {
            "identifier": {
                "type": "string",
                "description": "REQUIRED. App name, path, or bundle ID."
            }
        },
        "required": ["identifier"]
    },
),

src/mcp_remote_macos_use/server.py:280-281 (registration)
Registration in the tool dispatch handler: maps tool name to the handler function.
```
elif name == "remote_macos_open_application":
    return handle_remote_macos_open_application(arguments)
```

src/mcp_remote_macos_use/server.py:33-42 (registration)

Import of the handler function for use in tool registration.

from action_handlers import (
    handle_remote_macos_get_screen,
    handle_remote_macos_mouse_scroll,
    handle_remote_macos_send_keys,
    handle_remote_macos_mouse_move,
    handle_remote_macos_mouse_click,
    handle_remote_macos_mouse_double_click,
    handle_remote_macos_open_application,
    handle_remote_macos_mouse_drag_n_drop
)

MCP Remote macOS Control Server