MCP Remote macOS Control Server

Instructions

Implementation Reference

• src/action_handlers.py:43-76 (handler)

  The primary handler function for the 'remote_macos_get_screen' tool. It uses environment variables for VNC connection details, calls capture_vnc_screen to get the screen image, encodes it as base64 PNG, and returns it as ImageContent along with dimensions.

  async def handle_remote_macos_get_screen(arguments: dict[str, Any]) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:
      """Connect to a remote MacOs machine and get a screenshot of the remote desktop."""
      # Use environment variables
      host = MACOS_HOST
      port = MACOS_PORT
      password = MACOS_PASSWORD
      username = MACOS_USERNAME
      encryption = VNC_ENCRYPTION
  
      # Capture screen using helper method
      success, screen_data, error_message, dimensions = await capture_vnc_screen(
          host=host, port=port, password=password, username=username, encryption=encryption
      )
  
      if not success:
          return [types.TextContent(type="text", text=error_message)]
  
      # Encode image in base64
      base64_data = base64.b64encode(screen_data).decode('utf-8')
  
      # Return image content with dimensions
      width, height = dimensions
      return [
          types.ImageContent(
              type="image",
              data=base64_data,
              mimeType="image/png",
              alt_text=f"Screenshot from remote MacOs machine at {host}:{port}"
          ),
          types.TextContent(
              type="text",
              text=f"Image dimensions: {width}x{height}"
          )
      ]

• src/mcp_remote_macos_use/server.py:134-140 (schema)

  The tool schema definition in the list_tools() function, specifying name, description, and empty input schema (no parameters required).

      name="remote_macos_get_screen",
      description="Connect to a remote MacOs machine and get a screenshot of the remote desktop. Uses environment variables for connection details.",
      inputSchema={
          "type": "object",
          "properties": {}
      },
  ),

• src/mcp_remote_macos_use/server.py:262-263 (registration)

  Tool dispatch/registration in the call_tool() handler: checks tool name and delegates to the specific handler function.

  if name == "remote_macos_get_screen":
      return await handle_remote_macos_get_screen(arguments)

• src/vnc_client.py:19-91 (helper)

  Core helper function called by the handler to establish VNC connection using VNCClient, capture the screen, resize to 1366x768, and return PNG bytes or error.

  async def capture_vnc_screen(host: str, port: int, password: str, username: Optional[str] = None,
                               encryption: str = "prefer_on") -> Tuple[bool, Optional[bytes], Optional[str], Optional[Tuple[int, int]]]:
      """Capture a screenshot from a remote MacOs machine.
  
      Args:
          host: remote MacOs machine hostname or IP address
          port: remote MacOs machine port
          password: remote MacOs machine password
          username: remote MacOs machine username (optional)
          encryption: Encryption preference (default: "prefer_on")
  
      Returns:
          Tuple containing:
          - success: True if the operation was successful
          - screen_data: PNG image data if successful, None otherwise
          - error_message: Error message if unsuccessful, None otherwise
          - dimensions: Tuple of (width, height) if successful, None otherwise
      """
      logger.debug(f"Connecting to remote MacOs machine at {host}:{port} with encryption: {encryption}")
  
      # Initialize VNC client
      vnc = VNCClient(host=host, port=port, password=password, username=username, encryption=encryption)
  
      try:
          # Connect to remote MacOs machine
          success, error_message = vnc.connect()
          if not success:
              detailed_error = f"Failed to connect to remote MacOs machine at {host}:{port}. {error_message}\n"
              detailed_error += "This VNC client only supports Apple Authentication (protocol 30). "
              detailed_error += "Please ensure the remote MacOs machine supports this protocol. "
              detailed_error += "For macOS, enable Screen Sharing in System Preferences > Sharing."
              return False, None, detailed_error, None
  
          # Capture screen
          screen_data = vnc.capture_screen()
  
          if not screen_data:
              return False, None, f"Failed to capture screenshot from remote MacOs machine at {host}:{port}", None
  
          # Save original dimensions for reference
          original_dims = (vnc.width, vnc.height)
  
          # Scale the image to FWXGA resolution (1366x768)
          target_width, target_height = 1366, 768
  
          try:
              # Convert bytes to PIL Image
              image_data = io.BytesIO(screen_data)
              img = Image.open(image_data)
  
              # Resize the image to the target resolution
              scaled_img = img.resize((target_width, target_height), Image.Resampling.LANCZOS)
  
              # Convert back to bytes
              output_buffer = io.BytesIO()
              scaled_img.save(output_buffer, format='PNG')
              output_buffer.seek(0)
              scaled_screen_data = output_buffer.getvalue()
  
              logger.info(f"Scaled image from {original_dims[0]}x{original_dims[1]} to {target_width}x{target_height}")
  
              # Return success with scaled screen data and target dimensions
              return True, scaled_screen_data, None, (target_width, target_height)
  
          except Exception as e:
              logger.warning(f"Failed to scale image: {str(e)}. Returning original image.")
              # Return the original image if scaling fails
              return True, screen_data, None, original_dims
  
      finally:
          # Close VNC connection
          vnc.close()