Android Mobile MCP

Instructions

Implementation Reference

• main.py:99-109 (registration)

  Registration of the 'mobile_dump_ui' tool using the @mcp.tool() decorator. This function serves as the entry point, checking device initialization before delegating to the internal implementation.
  @mcp.tool() def mobile_dump_ui() -> str: """Get UI elements from Android screen as JSON with hierarchical structure. Returns a JSON structure where elements contain their child elements, showing parent-child relationships. Only includes focusable elements or elements with text/content_desc/hint attributes. """ if device is None: return "Error: Device not initialized. Please call mobile_init() first to establish connection with Android device." return _mobile_dump_ui()
• main.py:110-123 (handler)

  Core handler logic for dumping the UI hierarchy: retrieves XML dump, parses it into an ElementTree, clears UI coordinates, extracts structured UI elements, and returns them as a string representation.
  def _mobile_dump_ui(): try: xml_content = device.dump_hierarchy() root = ET.fromstring(xml_content) global current_ui_state ui_coords.clear() ui_elements = extract_ui_elements(root) return str(ui_elements) except Exception as e: return f"Error processing XML: {str(e)}"
• main.py:36-84 (helper)

  Key helper function that recursively traverses the UI XML tree to extract relevant elements (focusable or with text), computes center coordinates, collects child texts if needed, filters duplicates, and builds a hierarchical JSON-like structure.
  def extract_ui_elements(element): resource_id = element.get('resource-id', '') text = element.get('text', '').strip() content_desc = element.get('content-desc', '').strip() hint = element.get('hint', '').strip() bounds = parse_bounds(element.get('bounds', '')) focusable = element.get('focusable', 'false').lower() == 'true' has_text = bool(text or content_desc or hint) children = [] for child in element: children.extend(extract_ui_elements(child)) if not (focusable or has_text): return children display_text = text or content_desc or hint if focusable and not display_text: child_texts = get_children_texts(element) display_text = ' '.join(child_texts).strip() element_info = { "text": display_text, "class": element.get('class', ''), "coordinates": {"x": bounds["x"], "y": bounds["y"]} if bounds else None } global ui_coords ui_coords.add((bounds["x"], bounds["y"])) if resource_id: element_info["resource_id"] = resource_id if children: filtered_children = [] for child in children: child_text = child.get("text", "") child_coords = child.get("coordinates") if not (child_text == element_info["text"] and child_coords == element_info["coordinates"]): filtered_children.append(child) if filtered_children: element_info["children"] = filtered_children return [element_info]
• main.py:14-24 (helper)

  Helper function to parse bounds string from UI XML into center coordinates and full bounds array.
  def parse_bounds(bounds_str): if not bounds_str or bounds_str == '': return None try: bounds = bounds_str.replace('[', '').replace(']', ',').split(',') x1, y1, x2, y2 = map(int, bounds[:4]) center_x = (x1 + x2) // 2 center_y = (y1 + y2) // 2 return {"x": center_x, "y": center_y, "bounds": [x1, y1, x2, y2]} except: return None
• main.py:26-35 (helper)

  Helper to collect unique text from child elements for use in display_text when parent lacks text but is focusable.
  def get_children_texts(element): child_texts = [] """Check if element has any focusable children""" for child in list(element.iter())[1:]: child_text = child.get('text', '').strip() if child_text and child_text not in child_texts: child_texts.append(child_text) return child_texts