AdsPower LocalAPI MCP Server

Instructions

Implementation Reference

• src/handlers/browser.ts:15-47 (handler)

  Core handler function for the 'open-browser' tool. Constructs query parameters based on input and makes an axios GET request to the local API endpoint to launch a browser instance, returning formatted connection details (e.g., ws.puppeteer, ws.cdp) on success or throws an error.
  async openBrowser({ serialNumber, userId, ipTab, launchArgs, clearCacheAfterClosing, cdpMask }: OpenBrowserParams) { const params = new URLSearchParams(); if (serialNumber) { params.set('serial_number', serialNumber); } if (userId) { params.set('user_id', userId); } if (ipTab) { params.set('open_tabs', ipTab); } if (launchArgs) { params.set('launch_args', launchArgs); } if (clearCacheAfterClosing) { params.set('clear_cache_after_closing', clearCacheAfterClosing); } if (cdpMask) { params.set('cdp_mask', cdpMask); } params.set('open_tabs', '0'); const response = await axios.get(`${LOCAL_API_BASE}${API_ENDPOINTS.START_BROWSER}`, { params }); if (response.data.code === 0) { return `Browser opened successfully with: ${Object.entries(response.data.data).map(([key, value]) => { if (value && typeof value === 'object') { return Object.entries(value).map(([key, value]) => `ws.${key}: ${value}`).join('\n'); } return `${key}: ${value}`; }).join('\n')}`; } throw new Error(`Failed to open browser: ${response.data.msg}`); },
• src/types/schemas.ts:99-106 (schema)

  Zod input schema defining parameters for the open-browser tool, including optional fields like serialNumber, userId, launch args, etc.
  openBrowserSchema: z.object({ serialNumber: z.string().optional().describe('The serial number of the browser to open'), userId: z.string().optional().describe('The browser id of the browser to open'), ipTab: z.enum(['0', '1']).optional().describe('The ip tab of the browser, 0 is not use ip tab, 1 is use ip tab, default is 0'), launchArgs: z.string().optional().describe(`The launch args of the browser, use chrome launch args, eg: ${JSON.stringify(["--blink-settings=imagesEnabled=false", "--disable-notifications"])}, or vista url, eg: ${JSON.stringify(["https://www.adspower.net"])}`), clearCacheAfterClosing: z.enum(['0', '1']).optional().describe('The clear cache after closing of the browser, 0 is not clear cache after closing, 1 is clear cache after closing, default is 0'), cdpMask: z.enum(['0', '1']).optional().describe('The cdp mask of the browser, 0 is not use cdp mask, 1 is use cdp mask, default is 0'), }).strict(),
• src/utils/toolRegister.ts:11-12 (registration)

  MCP server tool registration for 'open-browser', specifying name, description, input shape from schema, and wrapped handler function.
  server.tool('open-browser', 'Open the browser, both environment and profile mean browser', schemas.openBrowserSchema.shape, wrapHandler(browserHandlers.openBrowser));
• src/utils/handlerWrapper.ts:4-39 (helper)

  Helper function that wraps raw handlers to conform to MCP CallToolResult format, converting string results to text content and handling browser-related errors by resetting the browser connection.
  export function wrapHandler(handler: Function) { return async (params: any): Promise<CallToolResult> => { try { const content = await handler(params); if (typeof content === 'string') { return { content: [{ type: 'text' as const, text: content }] }; } return { content }; } catch (error) { let errorMessage = error instanceof Error ? error.message : String(error); if ( errorMessage.includes("Target page, context or browser has been closed") || errorMessage.includes("Target closed") || errorMessage.includes("Browser has been disconnected") || errorMessage.includes("Protocol error") || errorMessage.includes("Connection closed") ) { await browser.resetBrowser(); errorMessage = `Browser connection error: ${errorMessage}. Connection has been reset - please retry the operation.`; } return { content: [{ type: 'text' as const, text: errorMessage }] }; } }; }