ADB MCP Server

Implementation Reference

• src/index.ts:481-496 (handler)

  The handler function for the 'adb_shell' tool. It logs the command, builds device-specific arguments, validates the command is not empty, and executes the ADB shell command via executeAdbCommand.

  async (args: z.infer<typeof AdbShellSchema>, _extra: RequestHandlerExtra) => {
    log(LogLevel.INFO, `Executing shell command: ${args.command}`);
    
    const deviceArgs = buildDeviceArgs(args.device);
    const trimmedCommand = args.command.trim();
    if (!trimmedCommand) {
      const message = "Shell command must not be empty";
      log(LogLevel.ERROR, message);
      return {
        content: [{ type: "text" as const, text: message }],
        isError: true
      };
    }
  
    return executeAdbCommand([...deviceArgs, "shell", trimmedCommand], "Error executing shell command");
  },

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

  Registration of the 'adb_shell' tool using server.tool, specifying name, input schema, handler function, and description.

  server.tool(
    "adb_shell",
    AdbShellSchema.shape,
    async (args: z.infer<typeof AdbShellSchema>, _extra: RequestHandlerExtra) => {
      log(LogLevel.INFO, `Executing shell command: ${args.command}`);
      
      const deviceArgs = buildDeviceArgs(args.device);
      const trimmedCommand = args.command.trim();
      if (!trimmedCommand) {
        const message = "Shell command must not be empty";
        log(LogLevel.ERROR, message);
        return {
          content: [{ type: "text" as const, text: message }],
          isError: true
        };
      }
  
      return executeAdbCommand([...deviceArgs, "shell", trimmedCommand], "Error executing shell command");
    },
    { description: ADB_SHELL_TOOL_DESCRIPTION }

• src/types.ts:46-49 (schema)

  Input schema object defining the parameters for the adb_shell tool: command (required string) and device (optional string).

  export const adbShellInputSchema = {
    command: z.string().describe("Shell command to execute on the device"),
    device: z.string().optional().describe("Specific device ID (optional)")
  };

• src/types.ts:103-103 (schema)

  Zod schema creation for AdbShellSchema by wrapping the input schema object.

  export const AdbShellSchema = z.object(adbShellInputSchema);

• src/index.ts:197-251 (helper)

  Helper function used by the adb_shell handler to execute the actual ADB command, handle errors, and format the response.

  async function executeAdbCommand(args: string[], errorMessage: string) {
    const commandString = ["adb", ...args].join(" ");
    try {
      log(LogLevel.DEBUG, `Executing command: ${commandString}`);
      const { stdout, stderr } = await runAdb(args);
      const stderrText = stderr.trim();
  
      // Some ADB commands output to stderr but are not errors
      if (stderrText && !stdout.includes("List of devices attached") && !stdout.includes("Success")) {
        const nonErrorWarnings = [
          "Warning: Activity not started, its current task has been brought to the front",
          "Warning: Activity not started, intent has been delivered to currently running top-most instance."
        ];
  
        if (nonErrorWarnings.some((warning) => stderrText.includes(warning))) {
          log(LogLevel.WARN, `Command warning (not error): ${stderrText}`);
          return {
            content: [{
              type: "text" as const,
              text: stderrText.replace(/^Error: /, "") // Remove any 'Error: ' prefix if present
            }]
            // Do NOT set isError
          };
        }
        log(LogLevel.ERROR, `Command error: ${stderrText}`);
        return {
          content: [{
            type: "text" as const,
            text: `Error: ${stderrText}`
          }],
          isError: true
        };
      }
  
      log(LogLevel.DEBUG, `Command successful: ${commandString}`);
      const commandSummary = args[0] ? `${args[0]}` : commandString;
      log(LogLevel.INFO, `ADB command executed successfully: ${commandSummary}`);
      return {
        content: [{
          type: "text" as const,
          text: stdout || "Command executed successfully"
        }]
      };
    } catch (error) {
      const errorMsg = error instanceof Error ? error.message : String(error);
      log(LogLevel.ERROR, `${errorMessage}: ${errorMsg}`);
      return {
        content: [{
          type: "text" as const,
          text: `${errorMessage}: ${errorMsg}`
        }],
        isError: true
      };
    }
  }