Android MCP Server

Instructions

Implementation Reference

• src/handlers.ts:319-343 (handler)

  The primary handler function for the android_uiautomator_click tool. Validates the resourceId input and delegates the click action to the ADBWrapper's clickElementByResourceId method.

  export async function uiautomatorClickHandler(
    adb: ADBWrapper,
    args: any
  ): Promise<{ content: Array<{ type: string; text: string }> }> {
    const { resourceId, deviceSerial } = args as UIAutomatorClickArgs;
  
    if (!resourceId || typeof resourceId !== 'string') {
      throw new Error('Invalid resource ID: resourceId must be a non-empty string');
    }
  
    try {
      await adb.clickElementByResourceId(resourceId, deviceSerial);
  
      return {
        content: [
          {
            type: 'text',
            text: `Successfully clicked element with resource-id: ${resourceId}`,
          },
        ],
      };
    } catch (error) {
      throw new Error(`UIAutomator click failed: ${error instanceof Error ? error.message : String(error)}`);
    }
  }

• src/adb-wrapper.ts:487-514 (helper)

  Core implementation that dumps the UI hierarchy using uiautomator, parses the XML to extract element bounds, computes the center coordinates, and performs a touch action at the center.

  async clickElementByResourceId(resourceId: string, deviceSerial?: string): Promise<void> {
    const device = await this.getTargetDevice(deviceSerial);
    // Get the hierarchy to find coordinates
    const hierarchyFile = '/sdcard/window_dump.xml';
    await this.exec(['shell', 'uiautomator', 'dump', hierarchyFile], device);
    
    const { stdout } = await this.exec(['shell', 'cat', hierarchyFile], device);
    await this.exec(['shell', 'rm', hierarchyFile], device);
    
    // Extract bounds from XML
    const boundsRegex = new RegExp(`resource-id="${resourceId}"[^>]*bounds="\\[(\\d+),(\\d+)\\]\\[(\\d+),(\\d+)\\]"`);
    const match = stdout.match(boundsRegex);
    
    if (match) {
      const x1 = parseInt(match[1], 10);
      const y1 = parseInt(match[2], 10);
      const x2 = parseInt(match[3], 10);
      const y2 = parseInt(match[4], 10);
      
      // Click at the center of the element
      const centerX = Math.floor((x1 + x2) / 2);
      const centerY = Math.floor((y1 + y2) / 2);
      
      await this.touch(centerX, centerY, 100, device);
    } else {
      throw new Error(`Element with resource-id ${resourceId} not found in UI hierarchy`);
    }
  }

• src/index.ts:189-206 (schema)

  MCP tool schema definition including input schema with required resourceId and optional deviceSerial.

  {
    name: 'android_uiautomator_click',
    description: 'Click on a UI element by resource ID using UIAutomator',
    inputSchema: {
      type: 'object',
      properties: {
        resourceId: {
          type: 'string',
          description: 'Resource ID of the element to click (e.g., com.example.app:id/button_submit)',
        },
        deviceSerial: {
          type: 'string',
          description: 'Specific device serial number to target (optional)',
        },
      },
      required: ['resourceId'],
    },
  },

• src/index.ts:478-479 (registration)

  Registration of the tool handler in the CallToolRequestSchema switch statement.

  case 'android_uiautomator_click':
    return await uiautomatorClickHandler(this.adb, args);

• src/handlers.ts:44-47 (schema)

  TypeScript interface defining the input arguments for the handler.

  interface UIAutomatorClickArgs {
    resourceId: string;
    deviceSerial?: string;
  }