MCP Remote macOS Control Server

Instructions

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
  )