android_start_emulator

Start an Android emulator for development and testing by specifying the AVD name and optional configuration settings like GPU mode and console port.

Instructions

Start an Android emulator

Input Schema

TableJSON Schema

Name	Required	Description	Default
`avdName`	Yes	AVD name to start
`options`	No

Implementation Reference

src/tools/android.ts:560-621 (handler)

The handler function for android_start_emulator tool. Validates input using Zod schema, checks if emulator is already running, spawns the emulator process with options, tracks the PID in runningEmulators map, and sets up exit handler.

handler: async (args: any) => {
  const validation = AndroidEmulatorStartSchema.safeParse(args);
  if (!validation.success) {
    throw new Error(`Invalid request: ${validation.error.message}`);
  }

  const { avdName, options = {} } = validation.data;

  // Check if emulator is already running
  if (runningEmulators.has(avdName)) {
    return {
      success: true,
      data: {
        avdName,
        status: 'already_running',
        pid: runningEmulators.get(avdName),
        message: 'Emulator is already running',
      },
    };
  }

  const emulator_args = ['-avd', avdName];
  
  if (options.noWindow) {
    emulator_args.push('-no-window');
  }
  
  if (options.port) {
    emulator_args.push('-port', options.port.toString());
  }
  
  if (options.gpu) {
    emulator_args.push('-gpu', options.gpu);
  }

  // Start emulator in background
  const emulatorProcess = spawn('emulator', emulator_args, {
    detached: true,
    stdio: 'ignore',
  });

  // Track the process
  runningEmulators.set(avdName, emulatorProcess.pid!);

  // Handle process exit
  emulatorProcess.on('exit', () => {
    runningEmulators.delete(avdName);
  });

  // Unref to allow the parent process to exit
  emulatorProcess.unref();

  return {
    success: true,
    data: {
      avdName,
      pid: emulatorProcess.pid,
      status: 'started',
      options,
    },
  };
}

src/tools/android.ts:87-94 (schema)

Zod validation schema used in the handler for input parameters: avdName (required string), options (optional object with noWindow boolean, port number 5554-5682, gpu enum).

const AndroidEmulatorStartSchema = z.object({
  avdName: z.string().min(1),
  options: z.object({
    noWindow: z.boolean().optional(),
    port: z.number().min(5554).max(5682).optional(),
    gpu: z.enum(['auto', 'host', 'swiftshader_indirect', 'angle_indirect', 'guest']).optional(),
  }).optional(),
});

src/tools/android.ts:538-622 (registration)

Registration of the android_start_emulator tool within the createAndroidTools function. Defines name, description, inputSchema (JSON schema), and references the handler function.

tools.set('android_start_emulator', {
  name: 'android_start_emulator',
  description: 'Start an Android emulator',
  inputSchema: {
    type: 'object',
    properties: {
      avdName: { type: 'string', minLength: 1, description: 'AVD name to start' },
      options: {
        type: 'object',
        properties: {
          noWindow: { type: 'boolean', description: 'Run without UI window' },
          port: { type: 'number', minimum: 5554, maximum: 5682, description: 'Console port number' },
          gpu: { 
            type: 'string', 
            enum: ['auto', 'host', 'swiftshader_indirect', 'angle_indirect', 'guest'],
            description: 'GPU acceleration mode'
          }
        }
      }
    },
    required: ['avdName']
  },
  handler: async (args: any) => {
    const validation = AndroidEmulatorStartSchema.safeParse(args);
    if (!validation.success) {
      throw new Error(`Invalid request: ${validation.error.message}`);
    }

    const { avdName, options = {} } = validation.data;

    // Check if emulator is already running
    if (runningEmulators.has(avdName)) {
      return {
        success: true,
        data: {
          avdName,
          status: 'already_running',
          pid: runningEmulators.get(avdName),
          message: 'Emulator is already running',
        },
      };
    }

    const emulator_args = ['-avd', avdName];
    
    if (options.noWindow) {
      emulator_args.push('-no-window');
    }
    
    if (options.port) {
      emulator_args.push('-port', options.port.toString());
    }
    
    if (options.gpu) {
      emulator_args.push('-gpu', options.gpu);
    }

    // Start emulator in background
    const emulatorProcess = spawn('emulator', emulator_args, {
      detached: true,
      stdio: 'ignore',
    });

    // Track the process
    runningEmulators.set(avdName, emulatorProcess.pid!);

    // Handle process exit
    emulatorProcess.on('exit', () => {
      runningEmulators.delete(avdName);
    });

    // Unref to allow the parent process to exit
    emulatorProcess.unref();

    return {
      success: true,
      data: {
        avdName,
        pid: emulatorProcess.pid,
        status: 'started',
        options,
      },
    };
  }
});

src/utils/tool-categories.ts:142-150 (helper)

Metadata registration in tool registry: categorizes as ESSENTIAL android tool requiring EMULATOR, with performance expectations.

'android_start_emulator': {
  name: 'android_start_emulator',
  category: ToolCategory.ESSENTIAL,
  platform: 'android',
  requiredTools: [RequiredTool.EMULATOR],
  description: 'Start Android emulator',
  safeForTesting: false,
  performance: { expectedDuration: 60000, timeout: 180000 }
},

MCP Mobile Server