mcp-remote-macos-use

Instructions

Implementation Reference

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

  The handler function that executes the tool logic: opens Spotlight with Cmd+Space, types the app identifier, and presses Enter to launch it via VNC key events.
  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 (registration)

  Tool registration in the list_tools() method, including name, description, and input schema definition.
  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)

  Dispatch logic in the call_tool() handler that routes the tool call to the implementation function.
  elif name == "remote_macos_open_application": return handle_remote_macos_open_application(arguments)
• src/mcp_remote_macos_use/server.py:221-229 (schema)

  Input schema definition for the tool, specifying the required 'identifier' parameter.
  inputSchema={ "type": "object", "properties": { "identifier": { "type": "string", "description": "REQUIRED. App name, path, or bundle ID." } }, "required": ["identifier"]