browser_create_instance
Launch a new browser instance for automated testing or web scraping with configurable browser type, headless mode, and viewport settings.
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 | |
| viewport | No | Viewport size | |
| userAgent | No | User agent string | |
| metadata | No | Instance metadata |
Implementation Reference
- src/tools.ts:21-60 (schema)Tool schema definition for 'browser_create_instance' including name, description, and detailed inputSchema with properties like browserType, headless, viewport, userAgent, metadata.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 case in BrowserTools.executeTools method that processes 'browser_create_instance' tool call, extracts 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/browser-manager.ts:162-227 (handler)Core implementation of createInstance in BrowserManager: launches Playwright browser based on config, handles proxy configuration, creates context and page, generates UUID, 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}` }; } }
- src/server.ts:40-45 (registration)MCP Server listTools request handler that returns the list of all tools (including browser_create_instance schema) from BrowserTools.getTools().this.server.setRequestHandler(ListToolsRequestSchema, async () => { const tools = this.browserTools.getTools(); return { tools: tools, }; });
- src/server.ts:48-75 (registration)MCP Server callTool request handler that routes tool execution to BrowserTools.executeTools based on tool name, formats success/error responses.this.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}` ); } });