aisquare-playwright-mcp

AiSquare Playwright MCP

Browser automation tools for AI assistants. Control web browsers directly from VS Code Copilot.

🚀 Quick Start (Recommended)

Step 1: Install the Extension

• Install AiSquare Playwright MCP from the VS Code Extensions Marketplace
• Restart VS Code

Step 2: Start the MCP Server

• Open Command Palette (Ctrl+Shift+P)
• Type "AiSquare: Start AiSquare Playwright MCP Server" and select it
• Wait for installation to complete (this may take a few minutes on first run)

Step 3: Connect to Copilot

• Open GitHub Copilot chat window
• Click the blue "Reload Tools" button
• Tools are now discovered and ready to use!

Step 4: Start Using Playwright Tools

Recommended tools to try first:

• browser_codegen_start - Start recording your browser actions
• browser_codegen_stop - Stop recording and get the generated code
• browser_navigate - Navigate to any website
• browser_snapshot - Take a snapshot of the current page

What You Can Do

• Automate any website - Fill forms, click buttons, navigate pages
• Generate test code - Record your actions and get Playwright test code
• Extract data - Get text, links, and information from web pages
• Take screenshots - Capture pages or specific elements
• Handle files - Upload and download files automatically

📋 Alternative Installation Methods

Manual Configuration (Advanced Users)

If you prefer manual setup or use other MCP clients:

VS Code/Cursor/Claude Desktop

Add to your MCP configuration:

{
  "mcpServers": {
    "aisquare-playwright": {
      "command": "npx",
      "args": ["aisquare-playwright-mcp@latest"]
    }
  }
}

Command Line Installation

npm install -g aisquare-playwright-mcp

🎯 Example Usage

Ask Copilot things like:

• "Navigate to google.com and search for 'AI tools'"
• "Take a screenshot of this page"
• "Start recording my browser actions"
• "Fill out this form with test data"
• "Click the login button and enter my credentials"

🛠 Available Tools

Essential Tools:

• browser_navigate - Go to any website
• browser_snapshot - See what's on the page
• browser_click - Click buttons and links
• browser_type - Fill in text fields
• browser_codegen_start/stop - Record and generate test code

Advanced Tools:

• Tab management, file uploads, PDF generation, network monitoring, and more

🔧 Troubleshooting

Tools not showing up?

• Make sure the MCP server is started (green status)
• Click "Reload Tools" in Copilot chat
• Restart VS Code if needed

Installation taking too long?

• The first run installs browser dependencies (300MB+)
• Check your internet connection
• Wait up to 5 minutes for completion

📚 More Information

• GitHub: github.com/aisquare/playwright-mcp
• npm Package: npmjs.com/package/aisquare-playwright-mcp

⚙️ Configuration Options

Command Line Arguments

You can customize the MCP server behavior using command line arguments:

{
  "mcpServers": {
    "aisquare-playwright": {
      "command": "npx",
      "args": [
        "aisquare-playwright-mcp@latest",
        "--headless",
        "--browser", "chrome"
      ]
    }
  }
}

Available Options:

--allowed-origins <origins>    Allow specific origins (semicolon-separated)
--blocked-origins <origins>    Block specific origins (semicolon-separated)
--browser <browser>           Browser to use: chrome, firefox, webkit, msedge
--headless                    Run browser in headless mode
--device <device>             Emulate device, e.g., "iPhone 15"
--viewport-size <size>        Browser viewport size, e.g., "1280,720"
--user-agent <ua>             Custom user agent string
--proxy-server <proxy>        Proxy server, e.g., "http://myproxy:3128"
--isolated                    Use isolated browser sessions
--port <port>                 Port for standalone server mode
--output-dir <path>           Directory for output files
--save-trace                  Save Playwright traces
--vision                      Use screenshot mode instead of snapshots

Configuration File

For complex setups, use a configuration file:

npx aisquare-playwright-mcp --config config.json

Example config.json:

{
  "browser": {
    "browserName": "chromium",
    "headless": false,
    "launchOptions": {
      "channel": "chrome",
      "args": ["--disable-web-security"]
    },
    "contextOptions": {
      "viewport": { "width": 1920, "height": 1080 },
      "userAgent": "Custom User Agent"
    }
  },
  "server": {
    "port": 3000,
    "host": "localhost"
  },
  "capabilities": ["core", "tabs", "pdf", "files"],
  "network": {
    "allowedOrigins": ["https://example.com"],
    "blockedOrigins": ["https://ads.example.com"]
  },
  "outputDir": "./output",
  "vision": false
}

Multiple Browser Setups

Run different browser configurations for different tasks:

{
  "mcpServers": {
    "playwright-chrome": {
      "command": "npx",
      "args": ["aisquare-playwright-mcp@latest", "--browser", "chrome"]
    },
    "playwright-firefox": {
      "command": "npx", 
      "args": ["aisquare-playwright-mcp@latest", "--browser", "firefox"]
    },
    "playwright-mobile": {
      "command": "npx",
      "args": ["aisquare-playwright-mcp@latest", "--device", "iPhone 15"]
    }
  }
}

Other MCP Clients

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "aisquare-playwright": {
      "command": "npx",
      "args": ["aisquare-playwright-mcp@latest"]
    }
  }
}

Cursor

Go to Cursor Settings → MCP → Add new MCP Server:

• Name: aisquare-playwright
• Command: npx
• Args: aisquare-playwright-mcp@latest

Docker

{
  "mcpServers": {
    "aisquare-playwright": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "aisquare/playwright-mcp"]
    }
  }
}

🧑‍💻 For Developers

Programmatic Usage

import { createConnection } from 'aisquare-playwright-mcp';
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';

// Create connection with custom config
const connection = await createConnection({
  browser: { 
    launchOptions: { headless: true },
    contextOptions: { viewport: { width: 1920, height: 1080 } }
  }
});

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

User Profile Locations

Browser profiles are stored at:

Windows: %USERPROFILE%\AppData\Local\aisquare-playwright\mcp-profile macOS: ~/Library/Caches/aisquare-playwright/mcp-profile
Linux: ~/.cache/aisquare-playwright/mcp-profile

Use --user-data-dir to customize the location.

License: Apache-2.0