MCP Remote macOS Control Server

Instructions

Implementation Reference

• src/action_handlers.py:156-219 (handler)

  The core handler function implementing the remote_macos_mouse_click tool. Connects to VNC server, scales input coordinates to target screen resolution, performs the mouse click via VNCClient.send_mouse_click, and returns status details.
  def handle_remote_macos_mouse_click(arguments: dict[str, Any]) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]: """Perform a mouse click action on a remote MacOs machine.""" # Use environment variables host = MACOS_HOST port = MACOS_PORT password = MACOS_PASSWORD username = MACOS_USERNAME encryption = VNC_ENCRYPTION # Get required parameters from arguments x = arguments.get("x") y = arguments.get("y") source_width = int(arguments.get("source_width", 1366)) source_height = int(arguments.get("source_height", 768)) button = int(arguments.get("button", 1)) if x is None or y is None: raise ValueError("x and y coordinates are required") # Ensure source dimensions are positive if source_width <= 0 or source_height <= 0: raise ValueError("Source dimensions must be positive values") # 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: # Get target screen dimensions target_width = vnc.width target_height = vnc.height # Scale coordinates scaled_x = int((x / source_width) * target_width) scaled_y = int((y / source_height) * target_height) # Ensure coordinates are within the screen bounds scaled_x = max(0, min(scaled_x, target_width - 1)) scaled_y = max(0, min(scaled_y, target_height - 1)) # Single click result = vnc.send_mouse_click(scaled_x, scaled_y, button, False) # Prepare the response with useful details scale_factors = { "x": target_width / source_width, "y": target_height / source_height } return [types.TextContent( type="text", text=f"""Mouse click (button {button}) from source ({x}, {y}) to target ({scaled_x}, {scaled_y}) {'succeeded' if result else 'failed'} Source dimensions: {source_width}x{source_height} Target dimensions: {target_width}x{target_height} Scale factors: {scale_factors['x']:.4f}x, {scale_factors['y']:.4f}y""" )] finally: # Close VNC connection vnc.close()
• src/mcp_remote_macos_use/server.py:188-202 (schema)

  Input schema definition for the remote_macos_mouse_click tool, specifying parameters for coordinates, scaling, and button.
  types.Tool( name="remote_macos_mouse_click", description="Perform a mouse click at specified coordinates on a remote MacOs machine, with automatic coordinate scaling. Uses environment variables for connection details.", inputSchema={ "type": "object", "properties": { "x": {"type": "integer", "description": "X coordinate for mouse position (in source dimensions)"}, "y": {"type": "integer", "description": "Y coordinate for mouse position (in source dimensions)"}, "source_width": {"type": "integer", "description": "Width of the reference screen for coordinate scaling", "default": 1366}, "source_height": {"type": "integer", "description": "Height of the reference screen for coordinate scaling", "default": 768}, "button": {"type": "integer", "description": "Mouse button (1=left, 2=middle, 3=right)", "default": 1} }, "required": ["x", "y"] }, ),
• src/mcp_remote_macos_use/server.py:274-275 (registration)

  Dispatch logic in the MCP server's call_tool handler that routes requests for 'remote_macos_mouse_click' to the handler function.
  elif name == "remote_macos_mouse_click": return handle_remote_macos_mouse_click(arguments)
• src/mcp_remote_macos_use/server.py:130-251 (registration)

  The tool is registered in the list_tools method by including it in the returned list of available tools.
  async def handle_list_tools() -> list[types.Tool]: """List available tools""" return [ 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": {} }, ), types.Tool( name="remote_macos_mouse_scroll", description="Perform a mouse scroll at specified coordinates on a remote MacOs machine, with automatic coordinate scaling. Uses environment variables for connection details.", inputSchema={ "type": "object", "properties": { "x": {"type": "integer", "description": "X coordinate for mouse position (in source dimensions)"}, "y": {"type": "integer", "description": "Y coordinate for mouse position (in source dimensions)"}, "source_width": {"type": "integer", "description": "Width of the reference screen for coordinate scaling", "default": 1366}, "source_height": {"type": "integer", "description": "Height of the reference screen for coordinate scaling", "default": 768}, "direction": { "type": "string", "description": "Scroll direction", "enum": ["up", "down"], "default": "down" } }, "required": ["x", "y"] }, ), types.Tool( name="remote_macos_send_keys", description="Send keyboard input to a remote MacOs machine. Uses environment variables for connection details.", inputSchema={ "type": "object", "properties": { "text": {"type": "string", "description": "Text to send as keystrokes"}, "special_key": {"type": "string", "description": "Special key to send (e.g., 'enter', 'backspace', 'tab', 'escape', etc.)"}, "key_combination": {"type": "string", "description": "Key combination to send (e.g., 'ctrl+c', 'cmd+q', 'ctrl+alt+delete', etc.)"} }, "required": [] }, ), types.Tool( name="remote_macos_mouse_move", description="Move the mouse cursor to specified coordinates on a remote MacOs machine, with automatic coordinate scaling. Uses environment variables for connection details.", inputSchema={ "type": "object", "properties": { "x": {"type": "integer", "description": "X coordinate for mouse position (in source dimensions)"}, "y": {"type": "integer", "description": "Y coordinate for mouse position (in source dimensions)"}, "source_width": {"type": "integer", "description": "Width of the reference screen for coordinate scaling", "default": 1366}, "source_height": {"type": "integer", "description": "Height of the reference screen for coordinate scaling", "default": 768} }, "required": ["x", "y"] }, ), types.Tool( name="remote_macos_mouse_click", description="Perform a mouse click at specified coordinates on a remote MacOs machine, with automatic coordinate scaling. Uses environment variables for connection details.", inputSchema={ "type": "object", "properties": { "x": {"type": "integer", "description": "X coordinate for mouse position (in source dimensions)"}, "y": {"type": "integer", "description": "Y coordinate for mouse position (in source dimensions)"}, "source_width": {"type": "integer", "description": "Width of the reference screen for coordinate scaling", "default": 1366}, "source_height": {"type": "integer", "description": "Height of the reference screen for coordinate scaling", "default": 768}, "button": {"type": "integer", "description": "Mouse button (1=left, 2=middle, 3=right)", "default": 1} }, "required": ["x", "y"] }, ), types.Tool( name="remote_macos_mouse_double_click", description="Perform a mouse double-click at specified coordinates on a remote MacOs machine, with automatic coordinate scaling. Uses environment variables for connection details.", inputSchema={ "type": "object", "properties": { "x": {"type": "integer", "description": "X coordinate for mouse position (in source dimensions)"}, "y": {"type": "integer", "description": "Y coordinate for mouse position (in source dimensions)"}, "source_width": {"type": "integer", "description": "Width of the reference screen for coordinate scaling", "default": 1366}, "source_height": {"type": "integer", "description": "Height of the reference screen for coordinate scaling", "default": 768}, "button": {"type": "integer", "description": "Mouse button (1=left, 2=middle, 3=right)", "default": 1} }, "required": ["x", "y"] }, ), 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"] }, ), types.Tool( name="remote_macos_mouse_drag_n_drop", description="Perform a mouse drag operation from start point and drop to end point on a remote MacOs machine, with automatic coordinate scaling.", inputSchema={ "type": "object", "properties": { "start_x": {"type": "integer", "description": "Starting X coordinate (in source dimensions)"}, "start_y": {"type": "integer", "description": "Starting Y coordinate (in source dimensions)"}, "end_x": {"type": "integer", "description": "Ending X coordinate (in source dimensions)"}, "end_y": {"type": "integer", "description": "Ending Y coordinate (in source dimensions)"}, "source_width": {"type": "integer", "description": "Width of the reference screen for coordinate scaling", "default": 1366}, "source_height": {"type": "integer", "description": "Height of the reference screen for coordinate scaling", "default": 768}, "button": {"type": "integer", "description": "Mouse button (1=left, 2=middle, 3=right)", "default": 1}, "steps": {"type": "integer", "description": "Number of intermediate points for smooth dragging", "default": 10}, "delay_ms": {"type": "integer", "description": "Delay between steps in milliseconds", "default": 10} }, "required": ["start_x", "start_y", "end_x", "end_y"] }, ), ]