Android MCP Server

Instructions

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'),
  });