find_element
Locate UI elements on Android screens using selectors like text, resource ID, or class name to identify buttons, text fields, or other components for automation tasks.
Instructions
Find a UI element on the Android screen matching the given selector criteria. Returns the first matching element with its properties and bounds. Use this to locate buttons, text fields, or any UI component before interacting with it.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| selector | Yes | Element selector with one or more criteria | |
| device_id | No | Device serial number |
Implementation Reference
- src/controllers/ui-tools.ts:67-103 (handler)The MCP tool registration and request handler for 'find_element'. It takes a selector and returns matching elements.
server.registerTool( 'find_element', { description: 'Find a UI element on the Android screen matching the given selector criteria. Returns the first matching element with its properties and bounds. Use this to locate buttons, text fields, or any UI component before interacting with it.', inputSchema: { selector: selectorSchema.describe('Element selector with one or more criteria'), device_id: z.string().optional().describe('Device serial number'), }, }, async ({ selector, device_id }) => { return await metrics.measure('find_element', device_id || 'default', async () => { try { const elements = await findElements(selector as ElementSelector, device_id); return { content: [{ type: 'text' as const, text: JSON.stringify({ success: true, found: elements.length, elements: elements.slice(0, 10), // Limit to first 10 }, null, 2), }], }; } catch (error) { return { content: [{ type: 'text' as const, text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : String(error), }, null, 2), }], }; } }); } ); - src/uiautomator/element-finder.ts:83-97 (handler)The core implementation of the findElement logic. It calls findElements and throws an error if no element is found.
export async function findElement( selector: ElementSelector, deviceId?: string ): Promise<FoundElement> { const found = await findElements(selector, deviceId); if (found.length === 0) { const selectorStr = Object.entries(selector) .map(([k, v]) => `${k}="${v}"`) .join(', '); throw new ElementNotFoundError(selectorStr, 'compound'); } return found[0]; } - src/controllers/ui-tools.ts:8-18 (schema)Input schema validation for the element selector used in 'find_element'.
const selectorSchema = z.object({ text: z.string().optional().describe('Exact text match'), textContains: z.string().optional().describe('Partial text match (case-insensitive)'), resourceId: z.string().optional().describe('Resource ID (e.g. com.app:id/button)'), className: z.string().optional().describe('Class name (e.g. android.widget.Button)'), contentDesc: z.string().optional().describe('Content description (accessibility label)'), contentDescContains: z.string().optional().describe('Partial content description match'), clickable: z.boolean().optional().describe('Filter by clickable state'), enabled: z.boolean().optional().describe('Filter by enabled state'), packageName: z.string().optional().describe('Filter by package name'), });