MCP Macaco Playwright

Enhanced Playwright Tools for Model Context Protocol (MCP) with Chrome DevTools Protocol (CDP) Support

Overview

MCP Macaco Playwright is a comprehensive browser automation server that provides AI agents with powerful web interaction capabilities through the Model Context Protocol. It combines Playwright's robust browser automation with CDP integration for advanced debugging and control scenarios.

Features

• Complete Browser Automation: Navigate, interact, and extract data from web pages
• Chrome DevTools Protocol (CDP) Support: Connect to existing browser instances
• AI-Optimized: Designed specifically for AI agents and automated workflows
• Comprehensive Tool Set: 50+ specialized functions for web automation
• Multi-Browser Support: Chrome, Firefox, Safari, and Edge
• Screenshot & Snapshot Capabilities: Visual and accessibility-based page capture
• Form Automation: Complete form filling and submission workflows
• Network Monitoring: Track requests, responses, and console messages

Installation

npm install mcp-macaco-playwright

Quick Start

import { createConnection } from "mcp-macaco-playwright";

// Create MCP server connection
const server = await createConnection();

// Use with MCP client
await client.callTool({
  name: "browser_navigate",
  arguments: { url: "https://example.com" },
});

Function Reference

Navigation Functions

browser_navigate

Navigate to a specific URL.

Parameters:

• url (string, required): The URL to navigate to

Example:

await client.callTool({
  name: "browser_navigate",
  arguments: { url: "https://github.com" },
});

browser_navigate_back

Go back to the previous page in browser history.

Parameters: None

Example:

await client.callTool({
  name: "browser_navigate_back",
  arguments: {},
});

browser_navigate_forward

Go forward to the next page in browser history.

Parameters: None

Example:

await client.callTool({
  name: "browser_navigate_forward",
  arguments: {},
});

Page Analysis Functions

browser_snapshot

Capture an accessibility snapshot of the current page for analysis and interaction.

Parameters: None

Example:

await client.callTool({
  name: "browser_snapshot",
  arguments: {},
});

browser_take_screenshot

Take a visual screenshot of the page or specific element.

Parameters:

• type (string, optional): Image format ('png' or 'jpeg', default: 'png')
• filename (string, optional): Custom filename for the screenshot
• element (string, optional): Human-readable element description
• ref (string, optional): Element reference from snapshot
• fullPage (boolean, optional): Capture full scrollable page

Example:

await client.callTool({
  name: "browser_take_screenshot",
  arguments: {
    type: "png",
    fullPage: true,
    filename: "homepage.png",
  },
});

Element Interaction Functions

browser_click

Click on a specific element on the page.

Parameters:

• element (string, required): Human-readable element description
• ref (string, required): Element reference from page snapshot

Example:

await client.callTool({
  name: "browser_click",
  arguments: {
    element: "Sign in button",
    ref: "button-signin-123",
  },
});

browser_double_click

Perform a double-click on an element.

Parameters:

• element (string, required): Human-readable element description
• ref (string, required): Element reference from page snapshot

Example:

await client.callTool({
  name: "browser_double_click",
  arguments: {
    element: "File icon",
    ref: "file-icon-456",
  },
});

browser_right_click

Perform a right-click to open context menu.

Parameters:

• element (string, required): Human-readable element description
• ref (string, required): Element reference from page snapshot

Example:

await client.callTool({
  name: "browser_right_click",
  arguments: {
    element: "Image thumbnail",
    ref: "img-thumb-789",
  },
});

Text Input Functions

browser_type

Type text into an editable element.

Parameters:

• element (string, required): Human-readable element description
• ref (string, required): Element reference from page snapshot
• text (string, required): Text to type
• submit (boolean, optional): Press Enter after typing
• slowly (boolean, optional): Type character by character

Example:

await client.callTool({
  name: "browser_type",
  arguments: {
    element: "Search input field",
    ref: "search-input-123",
    text: "playwright automation",
    submit: true,
  },
});

browser_press_key

Press a specific key on the keyboard.

Parameters:

• key (string, required): Key name (e.g., 'Enter', 'ArrowLeft', 'a')

Example:

await client.callTool({
  name: "browser_press_key",
  arguments: { key: "Escape" },
});

Form Functions

browser_select_option

Select options in a dropdown menu.

Parameters:

• element (string, required): Human-readable element description
• ref (string, required): Element reference from page snapshot
• values (array, required): Array of values to select

Example:

await client.callTool({
  name: "browser_select_option",
  arguments: {
    element: "Country dropdown",
    ref: "country-select-456",
    values: ["United States"],
  },
});

browser_check_checkbox

Check or uncheck a checkbox element.

Parameters:

• element (string, required): Human-readable element description
• ref (string, required): Element reference from page snapshot
• checked (boolean, required): Whether to check (true) or uncheck (false)

Example:

await client.callTool({
  name: "browser_check_checkbox",
  arguments: {
    element: "Terms and conditions checkbox",
    ref: "terms-checkbox-789",
    checked: true,
  },
});

browser_select_radio

Select a radio button.

Parameters:

• element (string, required): Human-readable element description
• ref (string, required): Element reference from page snapshot

Example:

await client.callTool({
  name: "browser_select_radio",
  arguments: {
    element: "Payment method: Credit Card",
    ref: "payment-radio-cc",
  },
});

browser_clear_input

Clear the content of an input field.

Parameters:

• element (string, required): Human-readable element description
• ref (string, required): Element reference from page snapshot

Example:

await client.callTool({
  name: "browser_clear_input",
  arguments: {
    element: "Email input field",
    ref: "email-input-123",
  },
});

Data Extraction Functions

browser_get_text

Extract text content or attribute values from elements.

Parameters:

• element (string, required): Human-readable element description
• ref (string, required): Element reference from page snapshot
• attribute (string, optional): Specific attribute to extract (e.g., 'href', 'src')

Example:

await client.callTool({
  name: "browser_get_text",
  arguments: {
    element: "Product price",
    ref: "price-display-456",
  },
});

browser_get_elements

Get multiple elements matching a selector.

Parameters:

• selector (string, required): CSS selector to find elements
• attribute (string, optional): Attribute to extract from each element

Example:

await client.callTool({
  name: "browser_get_elements",
  arguments: {
    selector: ".product-card h3",
    attribute: "textContent",
  },
});

Scrolling and Focus Functions

browser_scroll_to

Scroll to a specific element or coordinate position.

Parameters:

• element (string, optional): Human-readable element description
• ref (string, optional): Element reference from page snapshot
• x (number, optional): X coordinate to scroll to
• y (number, optional): Y coordinate to scroll to
• behavior (string, optional): Scroll behavior ('auto' or 'smooth')

Example:

await client.callTool({
  name: "browser_scroll_to",
  arguments: {
    element: "Footer section",
    ref: "footer-section-123",
    behavior: "smooth",
  },
});

browser_focus_element

Set focus on a specific element.

Parameters:

• element (string, required): Human-readable element description
• ref (string, required): Element reference from page snapshot

Example:

await client.callTool({
  name: "browser_focus_element",
  arguments: {
    element: "Search input",
    ref: "search-input-456",
  },
});

browser_blur_element

Remove focus from a specific element.

Parameters:

• element (string, required): Human-readable element description
• ref (string, required): Element reference from page snapshot

Example:

await client.callTool({
  name: "browser_blur_element",
  arguments: {
    element: "Email input",
    ref: "email-input-789",
  },
});

Wait Functions

browser_wait_for

Wait for specific conditions to be met.

Parameters:

• time (number, optional): Time to wait in seconds
• text (string, optional): Text to wait for to appear
• textGone (string, optional): Text to wait for to disappear

Example:

await client.callTool({
  name: "browser_wait_for",
  arguments: {
    text: "Loading complete",
    time: 5,
  },
});

Tab Management Functions

browser_tab_list

List all open browser tabs.

Parameters: None

Example:

await client.callTool({
  name: "browser_tab_list",
  arguments: {},
});

browser_tab_new

Open a new browser tab.

Parameters:

• url (string, optional): URL to navigate to

---