PlayMCP Browser Automation Server

A comprehensive MCP (Model Context Protocol) server for browser automation using Playwright. This server provides powerful tools for web scraping, testing, and automation.

PlayBrowser Automation Server MCP server

Features

Core Browser Controls

openBrowser - Launch a new browser instance with optional headless mode
navigate - Navigate to any URL
click - Click elements using CSS selectors
type - Type text into input fields
moveMouse - Move mouse to specific coordinates
scroll - Scroll the page by specified amounts
screenshot - Take screenshots of the page, viewport, or specific elements
closeBrowser - Close the browser instance

Page Content Extraction

getPageSource - Get the complete HTML source code
getPageText - Get the text content (stripped of HTML)
getPageTitle - Get the page title
getPageUrl - Get the current URL
getScripts - Extract all JavaScript code from the page
getStylesheets - Extract all CSS stylesheets
getMetaTags - Get all meta tags with their attributes
getLinks - Get all links with href, text, and title
getImages - Get all images with src, alt, and dimensions
getForms - Get all forms with their fields and attributes
getElementContent - Get HTML and text content of specific elements

Advanced Capabilities

executeJavaScript - Execute arbitrary JavaScript code on the page and return results

Available Tools Reference

Tool	Description	Required Parameters
`openBrowser`	Launch browser instance	`headless?: boolean, debug?: boolean`
`navigate`	Navigate to URL	`url: string`
`click`	Click element	`selector: string`
`type`	Type text into element	`selector: string, text: string`
`moveMouse`	Move mouse to coordinates	`x: number, y: number`
`scroll`	Scroll page	`x: number, y: number`
`screenshot`	Take screenshot	`path: string, type?: string, selector?: string`
`getPageSource`	Get HTML source	None
`getPageText`	Get text content	None
`getPageTitle`	Get page title	None
`getPageUrl`	Get current URL	None
`getScripts`	Get JavaScript code	None
`getStylesheets`	Get CSS stylesheets	None
`getMetaTags`	Get meta tags	None
`getLinks`	Get all links	None
`getImages`	Get all images	None
`getForms`	Get all forms	None
`getElementContent`	Get element content	`selector: string`
`executeJavaScript`	Run JavaScript	`script: string`
`closeBrowser`	Close browser	None

Installation

Complete Installation Steps

Prerequisites
- Node.js 16+ (download from nodejs.org)
- Git (for cloning the repository)

Clone and Setup

git clone <repository-url>
cd PlayMCP
npm install
npm run build

Install Playwright Browsers
```
npx playwright install
```
This downloads the necessary browser binaries (Chromium, Firefox, Safari).
Verify Installation
```
npm run start
```
You should see "Browser Automation MCP Server starting..." if everything is working.

Quick Installation

git clone <repository-url>
cd PlayMCP
npm install && npm run build && npx playwright install

Usage

As MCP Server

Add to your MCP configuration file:

Standard MCP Configuration:

{
  "servers": {
    "playmcp-browser": {
      "type": "stdio",
      "command": "node",
      "args": ["./dist/server.js"],
      "cwd": "/path/to/PlayMCP",
      "description": "Browser automation server using Playwright"
    }
  }
}

Alternative Configuration (works with VS Code GitHub Copilot):

{
  "servers": {
    "playmcp-browser": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/PlayMCP/dist/server.js"]
    }
  }
}

For Windows users:

{
  "servers": {
    "playmcp-browser": {
      "type": "stdio",
      "command": "node",
      "args": ["C:\\path\\to\\PlayMCP\\dist\\server.js"]
    }
  }
}

VS Code GitHub Copilot Integration

This MCP server is fully compatible with VS Code GitHub Copilot. After adding the configuration above to your MCP settings, you can use all browser automation tools directly within VS Code.

Configuration Examples

Claude Desktop (config.json location):

Windows: %APPDATA%\Claude\config.json
macOS: ~/Library/Application Support/Claude/config.json
Linux: ~/.config/Claude/config.json

VS Code MCP Extension: Add to your VS Code settings.json or MCP configuration file.

Example Full Configuration:

{
  "mcpServers": {
    "playmcp-browser": {
      "type": "stdio",
      "command": "node",
      "args": ["/Users/username/PlayMCP/dist/server.js"],
      "description": "Browser automation with Playwright"
    }
  }
}

Tool Examples

Basic Web Scraping:

// Open browser and navigate
await openBrowser({ headless: false, debug: true })
await navigate({ url: "https://example.com" })

// Extract content
const title = await getPageTitle()
const links = await getLinks()
const forms = await getForms()

Form Automation:

// Fill out a form
await click({ selector: "#login-button" })
await type({ selector: "#username", text: "[email protected]" })
await type({ selector: "#password", text: "password123" })
await click({ selector: "#submit" })

Page Interaction:

// Scroll and interact
await scroll({ x: 0, y: 500 })
await moveMouse({ x: 100, y: 200 })
await click({ selector: ".dropdown-menu" })

Advanced JavaScript Execution:

// Run custom JavaScript
await executeJavaScript({ 
  script: "document.querySelectorAll('h1').length" 
})

// Modify page content
await executeJavaScript({ 
  script: "document.body.style.backgroundColor = 'lightblue'" 
})

// Extract complex data
await executeJavaScript({ 
  script: `
    Array.from(document.querySelectorAll('article')).map(article => ({
      title: article.querySelector('h2')?.textContent,
      summary: article.querySelector('p')?.textContent
    }))
  `
})

Screenshot and Documentation:

// Take screenshots
await screenshot({ path: "./full-page.png", type: "page" })
await screenshot({ path: "./element.png", type: "element", selector: "#main-content" })

Quick Start

Install and setup:

git clone <repo-url> && cd PlayMCP
npm install && npm run build && npx playwright install

Add to your MCP client configuration

Start automating:

await openBrowser({ debug: true })
await navigate({ url: "https://news.ycombinator.com" })
const links = await getLinks()
console.log(`Found ${links.length} links`)

Development

src/server.ts - Main MCP server implementation
src/controllers/playwright.ts - Playwright browser controller
src/mcp/ - MCP protocol implementation
src/types/ - TypeScript type definitions

Requirements

System Requirements

Node.js 16+ (LTS version recommended)
Operating System: Windows, macOS, or Linux
Memory: At least 2GB RAM (4GB+ recommended for heavy usage)
Disk Space: ~500MB for browser binaries and dependencies

Dependencies

Playwright: Handles browser automation (automatically installed)
TypeScript: For compilation (dev dependency)
Browser Binaries: Downloaded via npx playwright install

Troubleshooting

Common Issues

"Browser not initialized" error
- Make sure to call openBrowser before other browser operations
- Check if Node.js version is 16 or higher

Playwright installation fails

# Try manual browser installation
npx playwright install chromium
# Or install all browsers
npx playwright install

Permission errors on Linux/macOS

# Make sure the script is executable
chmod +x dist/server.js

Path issues in MCP configuration
- Use absolute paths in the configuration
- On Windows, use double backslashes: C:\\path\\to\\PlayMCP\\dist\\server.js
- Verify the path exists: node /path/to/PlayMCP/dist/server.js
Browser crashes or timeouts
- Try running with headless: false for debugging
- Increase system memory if running multiple browser instances
- Check if antivirus software is blocking browser processes

Testing Your Installation

# Test the server directly
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node ./dist/server.js

You should see a JSON response listing all available tools.

License

MIT License