MCP Remote macOS Control Server

Instructions

Implementation Reference

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

  Primary handler function for the remote_macos_get_screen tool. Uses environment variables to connect to VNC server, captures screen via helper, encodes to base64 PNG ImageContent, and returns 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:253-292 (registration)

  MCP server tool dispatcher (handle_call_tool). Dispatches 'remote_macos_get_screen' calls to the handler function imported from action_handlers.py.
  @server.call_tool() async def handle_call_tool( name: str, arguments: dict[str, Any] | None ) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]: """Handle tool execution requests""" try: if not arguments: arguments = {} if name == "remote_macos_get_screen": return await handle_remote_macos_get_screen(arguments) elif name == "remote_macos_mouse_scroll": return handle_remote_macos_mouse_scroll(arguments) elif name == "remote_macos_send_keys": return handle_remote_macos_send_keys(arguments) elif name == "remote_macos_mouse_move": return handle_remote_macos_mouse_move(arguments) elif name == "remote_macos_mouse_click": return handle_remote_macos_mouse_click(arguments) elif name == "remote_macos_mouse_double_click": return handle_remote_macos_mouse_double_click(arguments) elif name == "remote_macos_open_application": return handle_remote_macos_open_application(arguments) elif name == "remote_macos_mouse_drag_n_drop": return handle_remote_macos_mouse_drag_n_drop(arguments) else: raise ValueError(f"Unknown tool: {name}") except Exception as e: logger.error(f"Error in handle_call_tool: {str(e)}", exc_info=True) return [types.TextContent(type="text", text=f"Error: {str(e)}")]
• src/mcp_remote_macos_use/server.py:133-140 (schema)

  Tool schema definition and registration in MCP server's list_tools(). No input parameters required.
  types.Tool( 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/vnc_client.py:19-91 (helper)

  Core VNC screen capture helper called by the handler. Creates VNCClient, connects using Apple Authentication (type 30), captures full screen framebuffer via RAW encoding, scales to 1366x768 PNG, returns data and dimensions.
  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()