> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/microsoft/playwright-mcp/llms.txt
> Use this file to discover all available pages before exploring further.

# Programmatic Usage

> Use Playwright MCP programmatically in your Node.js applications

Playwright MCP can be embedded directly into your Node.js applications, allowing you to create custom MCP servers or integrate browser automation into existing services.

## Installation

First, install the required packages:

```bash theme={null}
npm install @playwright/mcp @modelcontextprotocol/sdk
```

## Basic Usage

Create a headless Playwright MCP server with SSE transport:

```javascript theme={null}
import http from 'http';
import { createConnection } from '@playwright/mcp';
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';

http.createServer(async (req, res) => {
  // Handle SSE endpoint
  if (req.url === '/mcp' || req.url === '/messages') {
    // Create a headless Playwright MCP server
    const connection = await createConnection({
      browser: {
        launchOptions: {
          headless: true
        }
      }
    });

    // Set up SSE transport
    const transport = new SSEServerTransport('/messages', res);
    await connection.connect(transport);
  } else {
    res.writeHead(404);
    res.end('Not found');
  }
}).listen(8931);

console.log('Playwright MCP server listening on http://localhost:8931/mcp');
```

## Configuration Options

The `createConnection` function accepts the same configuration object as the JSON configuration file.

### Browser Configuration

```javascript theme={null}
const connection = await createConnection({
  browser: {
    browserName: 'chromium',
    headless: true,
    isolated: false,
    userDataDir: '/path/to/profile',
    launchOptions: {
      headless: true,
      args: ['--no-sandbox']
    },
    contextOptions: {
      viewport: { width: 1920, height: 1080 },
      userAgent: 'Custom User Agent'
    }
  }
});
```

### Capabilities

```javascript theme={null}
const connection = await createConnection({
  capabilities: ['core', 'pdf', 'vision'],
  browser: {
    launchOptions: {
      headless: true
    }
  }
});
```

### Network Filtering

```javascript theme={null}
const connection = await createConnection({
  network: {
    allowedOrigins: ['https://example.com:8080', 'http://localhost:*'],
    blockedOrigins: ['https://tracking.com']
  },
  browser: {
    launchOptions: {
      headless: true
    }
  }
});
```

### Timeouts

```javascript theme={null}
const connection = await createConnection({
  timeouts: {
    action: 10000,      // 10 seconds
    navigation: 120000  // 2 minutes
  },
  browser: {
    launchOptions: {
      headless: true
    }
  }
});
```

## SSE Transport

Server-Sent Events (SSE) transport is used for HTTP-based communication.

### Complete SSE Example

```javascript theme={null}
import http from 'http';
import { createConnection } from '@playwright/mcp';
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';

const PORT = 8931;

http.createServer(async (req, res) => {
  // Handle CORS preflight
  if (req.method === 'OPTIONS') {
    res.writeHead(204, {
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
      'Access-Control-Allow-Headers': 'Content-Type'
    });
    res.end();
    return;
  }

  // Handle MCP endpoint
  if (req.url === '/mcp') {
    try {
      const connection = await createConnection({
        browser: {
          browserName: 'chromium',
          launchOptions: {
            headless: true
          }
        },
        saveTrace: true,
        saveSession: true,
        outputDir: './output'
      });

      const transport = new SSEServerTransport('/messages', res);
      await connection.connect(transport);
    } catch (error) {
      console.error('Failed to create connection:', error);
      res.writeHead(500);
      res.end('Internal Server Error');
    }
  } else {
    res.writeHead(404);
    res.end('Not found');
  }
}).listen(PORT, () => {
  console.log(`Playwright MCP server listening on http://localhost:${PORT}/mcp`);
});
```

## Express.js Integration

```javascript theme={null}
import express from 'express';
import { createConnection } from '@playwright/mcp';
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';

const app = express();
const PORT = 8931;

app.get('/mcp', async (req, res) => {
  try {
    const connection = await createConnection({
      browser: {
        launchOptions: {
          headless: true
        }
      }
    });

    const transport = new SSEServerTransport('/messages', res);
    await connection.connect(transport);
  } catch (error) {
    console.error('Failed to create connection:', error);
    res.status(500).send('Internal Server Error');
  }
});

app.listen(PORT, () => {
  console.log(`Playwright MCP server listening on http://localhost:${PORT}/mcp`);
});
```

## Advanced Configuration

### Using Configuration File

```javascript theme={null}
import { readFileSync } from 'fs';
import { createConnection } from '@playwright/mcp';

const config = JSON.parse(readFileSync('./config.json', 'utf-8'));
const connection = await createConnection(config);
```

### With CDP Endpoint

```javascript theme={null}
const connection = await createConnection({
  browser: {
    cdpEndpoint: 'ws://localhost:9222/devtools/browser',
    cdpHeaders: {
      'Authorization': 'Bearer token123'
    },
    cdpTimeout: 30000
  }
});
```

### With Output Configuration

```javascript theme={null}
const connection = await createConnection({
  outputDir: './playwright-output',
  outputMode: 'file',
  saveSession: true,
  saveTrace: true,
  saveVideo: {
    width: 1280,
    height: 720
  },
  browser: {
    launchOptions: {
      headless: true
    }
  }
});
```

## Client Connection

Connect your MCP client to the programmatic server:

```json theme={null}
{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/mcp"
    }
  }
}
```

## Error Handling

```javascript theme={null}
import { createConnection } from '@playwright/mcp';

try {
  const connection = await createConnection({
    browser: {
      launchOptions: {
        headless: true
      }
    }
  });

  const transport = new SSEServerTransport('/messages', res);
  await connection.connect(transport);

  // Handle cleanup on connection close
  connection.onclose = () => {
    console.log('Connection closed');
  };
} catch (error) {
  console.error('Failed to create Playwright MCP connection:', error);
  throw error;
}
```

## Use Cases

<CardGroup cols={2}>
  <Card title="Custom MCP Gateway" icon="gateway">
    Build a gateway service that manages multiple Playwright browser instances for different users or tenants.
  </Card>

  <Card title="Integration Server" icon="plug">
    Embed Playwright MCP into existing services to add browser automation capabilities.
  </Card>

  <Card title="Testing Infrastructure" icon="vial">
    Create custom test runners that leverage MCP for browser automation.
  </Card>

  <Card title="Automation Platform" icon="robot">
    Build automation platforms that expose browser control through MCP to various clients.
  </Card>
</CardGroup>