browser_create_instance
Launch a parallel browser instance with customizable settings like browser type, headless mode, viewport size, and user agent for testing or automation tasks.
Instructions
Create a new browser instance
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| browserType | No | Browser type | chromium |
| headless | No | Whether to run in headless mode | |
| metadata | No | Instance metadata | |
| userAgent | No | User agent string | |
| viewport | No | Viewport size |
Implementation Reference
- src/tools.ts:20-60 (schema)Tool schema definition including inputSchema for browser_create_instance in BrowserTools.getTools(){ name: 'browser_create_instance', description: 'Create a new browser instance', inputSchema: { type: 'object', properties: { browserType: { type: 'string', enum: ['chromium', 'firefox', 'webkit'], description: 'Browser type', default: 'chromium' }, headless: { type: 'boolean', description: 'Whether to run in headless mode', default: true }, viewport: { type: 'object', properties: { width: { type: 'number', default: 1280 }, height: { type: 'number', default: 720 } }, description: 'Viewport size' }, userAgent: { type: 'string', description: 'User agent string' }, metadata: { type: 'object', properties: { name: { type: 'string', description: 'Instance name' }, description: { type: 'string', description: 'Instance description' }, tags: { type: 'array', items: { type: 'string' }, description: 'Tags' } }, description: 'Instance metadata' } } } },
- src/tools.ts:498-507 (handler)Handler logic in BrowserTools.executeTools() switch case that parses arguments and delegates to browserManager.createInstance()case 'browser_create_instance': return await this.browserManager.createInstance( { browserType: args.browserType || 'chromium', headless: args.headless ?? true, viewport: args.viewport || { width: 1280, height: 720 }, userAgent: args.userAgent }, args.metadata );
- src/server.ts:40-45 (registration)MCP list_tools request handler registration that provides all tools including browser_create_instance via BrowserTools.getTools()this.server.setRequestHandler(ListToolsRequestSchema, async () => { const tools = this.browserTools.getTools(); return { tools: tools, }; });
- src/server.ts:48-75 (registration)MCP call_tool request handler registration that dispatches to BrowserTools.executeTools() for tool executionthis.server.setRequestHandler(CallToolRequestSchema, async (request) => { const { name, arguments: args } = request.params; try { const result = await this.browserTools.executeTools(name, args || {}); if (result.success) { return { content: [ { type: 'text', text: JSON.stringify(result.data, null, 2), }, ], }; } else { throw new McpError(ErrorCode.InternalError, result.error || 'Tool execution failed'); } } catch (error) { if (error instanceof McpError) { throw error; } throw new McpError( ErrorCode.InternalError, `Tool execution failed: ${error instanceof Error ? error.message : error}` ); } });
- src/browser-manager.ts:162-227 (helper)Core implementation of browser instance creation in BrowserManager.createInstance(), called by the tool handler, launches browser, creates context/page, handles proxy, stores instance.async createInstance( browserConfig?: Partial<BrowserConfig>, metadata?: BrowserInstance['metadata'] ): Promise<ToolResult> { try { if (this.instances.size >= this.config.maxInstances) { return { success: false, error: `Maximum number of instances (${this.config.maxInstances}) reached` }; } const config = { ...this.config.defaultBrowserConfig, ...browserConfig }; const browser = await this.launchBrowser(config); const contextOptions: any = { viewport: config.viewport, ...config.contextOptions }; if (config.userAgent) { contextOptions.userAgent = config.userAgent; } // Add proxy configuration to context const effectiveProxy = this.getEffectiveProxy(browserConfig); if (effectiveProxy) { contextOptions.proxy = { server: effectiveProxy }; } const context = await browser.newContext(contextOptions); const page = await context.newPage(); const instanceId = uuidv4(); const instance: BrowserInstance = { id: instanceId, browser, context, page, createdAt: new Date(), lastUsed: new Date(), isActive: true, ...(metadata && { metadata }) }; this.instances.set(instanceId, instance); return { success: true, data: { instanceId, browserType: config.browserType, headless: config.headless, viewport: config.viewport, proxy: effectiveProxy, metadata }, instanceId }; } catch (error) { return { success: false, error: `Failed to create browser instance: ${error instanceof Error ? error.message : error}` }; } }