MCP Macaco Playwright logo

MCP Macaco Playwright

Organization
macacoai

MCP for Playwright

Publishermacacoai
Repositorymcp-playwright
LanguageJavaScript
Forks
1
Stars
1
Available tools
28
Transport typestdio
Categories
Browser AutomationSearch Web
Links
GitHub
  • Connect tools to AI workflows

    MCP Macaco Playwright exposes MCP capabilities that can be used by compatible AI clients and agents.

  • 28 available tools

    Browse the callable actions below, including names and descriptions when provided by the server.

  • Ready-to-copy setup

    Use the installation snippets to configure this server in your preferred MCP client.

  • Open source signals

    1 stars and 1 forks from the linked repository.

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

bash
npm install mcp-macaco-playwright

Quick Start

javascript
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:

javascript
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:

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

browser_navigate_forward

Go forward to the next page in browser history.

Parameters: None

Example:

javascript
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:

javascript
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:

javascript
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:

javascript
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:

javascript
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:

javascript
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:

javascript
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:

javascript
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:

javascript
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:

javascript
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:

javascript
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:

javascript
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:

javascript
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:

javascript
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:

javascript
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:

javascript
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:

javascript
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:

javascript
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:

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

browser_tab_new

Open a new browser tab.

Parameters:

  • url (string, optional): URL to navigate to in the new tab

Example:

javascript
await client.callTool({
  name: "browser_tab_new",
  arguments: { url: "https://example.com" },
});

browser_tab_close

Close a browser tab.

Parameters:

  • index (number, optional): Index of tab to close (closes current if not specified)

Example:

javascript
await client.callTool({
  name: "browser_tab_close",
  arguments: { index: 1 },
});

browser_tab_select

Switch to a specific tab by index.

Parameters:

  • index (number, required): Index of the tab to select

Example:

javascript
await client.callTool({
  name: "browser_tab_select",
  arguments: { index: 0 },
});

Network and Console Functions

browser_network_requests

Get all network requests made since page load.

Parameters: None

Example:

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

browser_console_messages

Get all console messages from the page.

Parameters: None

Example:

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

Chrome DevTools Protocol (CDP) Functions

browser_connect_cdp

Connect to an existing browser instance via CDP.

Parameters:

  • endpoint (string, required): CDP endpoint URL
  • timeout (number, optional): Connection timeout in milliseconds (default: 30000)

Example:

javascript
await client.callTool({
  name: "browser_connect_cdp",
  arguments: {
    endpoint: "ws://localhost:9222",
    timeout: 30000,
  },
});

browser_get_cdp_endpoints

Discover available CDP endpoints from running browsers.

Parameters:

  • port (number, optional): CDP port to check (default: 9222)
  • host (string, optional): Host to check (default: 'localhost')

Example:

javascript
await client.callTool({
  name: "browser_get_cdp_endpoints",
  arguments: {
    port: 9222,
    host: "localhost",
  },
});

browser_disconnect_cdp

Disconnect from the current CDP connection.

Parameters: None

Example:

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

JavaScript Evaluation Functions

browser_evaluate

Execute JavaScript code in the browser context.

Parameters:

  • script (string, required): JavaScript code to execute

Example:

javascript
await client.callTool({
  name: "browser_evaluate",
  arguments: {
    script: "document.title",
  },
});

Dialog Handling Functions

browser_handle_dialog

Handle browser dialogs (alert, confirm, prompt).

Parameters:

  • action (string, required): Action to take ('accept' or 'dismiss')
  • text (string, optional): Text to enter for prompt dialogs

Example:

javascript
await client.callTool({
  name: "browser_handle_dialog",
  arguments: {
    action: "accept",
    text: "User input",
  },
});

File Functions

browser_upload_file

Upload files to file input elements.

Parameters:

  • element (string, required): Human-readable element description
  • ref (string, required): Element reference from page snapshot
  • files (array, required): Array of file paths to upload

Example:

javascript
await client.callTool({
  name: "browser_upload_file",
  arguments: {
    element: "File upload input",
    ref: "file-input-123",
    files: ["/path/to/document.pdf"],
  },
});

PDF Functions

browser_save_pdf

Save the current page as a PDF.

Parameters:

  • filename (string, optional): Custom filename for the PDF
  • format (string, optional): Page format (e.g., 'A4', 'Letter')
  • landscape (boolean, optional): Use landscape orientation

Example:

javascript
await client.callTool({
  name: "browser_save_pdf",
  arguments: {
    filename: "report.pdf",
    format: "A4",
    landscape: false,
  },
});

Configuration

The MCP server can be configured with various options:

javascript
const config = {
  browser: {
    headless: false,
    viewport: { width: 1280, height: 720 },
    cdpEndpoint: "ws://localhost:9222", // Optional CDP connection
  },
  capabilities: ["core", "vision"], // Enable specific tool capabilities
};

const server = await createConnection(config);

Common Usage Patterns

Web Scraping Workflow

javascript
// Navigate to page
await client.callTool({
  name: "browser_navigate",
  arguments: { url: "https://example.com" },
});

// Take snapshot to analyze page structure
await client.callTool({
  name: "browser_snapshot",
  arguments: {},
});

// Extract data from elements
await client.callTool({
  name: "browser_get_text",
  arguments: {
    element: "Product title",
    ref: "product-title-123",
  },
});

Form Automation Workflow

javascript
// Navigate to form page
await client.callTool({
  name: "browser_navigate",
  arguments: { url: "https://example.com/contact" },
});

// Fill form fields
await client.callTool({
  name: "browser_type",
  arguments: {
    element: "Name input",
    ref: "name-input-123",
    text: "John Doe",
  },
});

// Submit form
await client.callTool({
  name: "browser_click",
  arguments: {
    element: "Submit button",
    ref: "submit-btn-456",
  },
});

CDP Integration Workflow

javascript
// Connect to existing browser
await client.callTool({
  name: "browser_connect_cdp",
  arguments: { endpoint: "ws://localhost:9222" },
});

// Work with existing tabs
await client.callTool({
  name: "browser_tab_list",
  arguments: {},
});

// Disconnect when done
await client.callTool({
  name: "browser_disconnect_cdp",
  arguments: {},
});

Troubleshooting

CDP Connection Issues

If you encounter CDP connection problems:

  1. Start Chrome with debugging enabled:

    bash
    google-chrome --remote-debugging-port=9222 --remote-debugging-address=0.0.0.0

  2. Verify the endpoint is accessible:

    bash
    curl http://localhost:9222/json/version

  3. Check for firewall or network restrictions

Browser Launch Issues

  • Ensure Playwright browsers are installed: npx playwright install
  • Check system dependencies: npx playwright install-deps
  • Verify sufficient system resources for browser instances

License

Apache License 2.0 - see LICENSE file for details.

Contributing

Contributions are welcome! Please see the contributing guidelines for more information.

Support

For issues and questions:

Installation

TypingMind
Prerequisites:

Node.js 18+

{
  "mcpServers": {
    "mcp-macaco-playwright": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-macaco-playwright"
      ]
    }
  }
}

Available Tools

  • browser_close

    Close the browser context, terminating all associated tabs and pages

  • browser_resize

    Resize the browser window to simulate different device viewports. Available options: mobile (375x667px - iPhone), tablet (768x1024px - iPad), desktop (1280x720px - HD)

  • browser_console_messages

    Retrieves all console messages (logs, errors, warnings, info, debug) from the browser tab's console output.

  • browser_handle_dialog

    Handles native browser dialogs that appear from JavaScript alert(), confirm(), or prompt() calls. Can accept/dismiss and provide text input for prompts.

  • browser_evaluate

    Runs custom JavaScript functions in the browser, targeting either the page or specific elements, and returns the result.

  • browser_file_upload

    Responds to browser file upload dialogs by selecting and uploading files. Works with file choosers triggered by elements.

  • browser_get_element

    Get complete information from an element including text content, input value, attributes, and metadata

  • browser_get_page_info

    Get basic information about the current page (title, URL, etc.)

  • browser_http_request

    Make HTTP requests (GET, POST, PUT, DELETE, PATCH) with custom headers and body

  • browser_install

    Install the browser specified in the config. Call this if you get an error about the browser not being installed.

  • browser_scroll_page

    Scroll the page to the very top or bottom. This is useful for quickly navigating to the beginning or end of long pages without needing to specify a particular element.

  • browser_element_focus

    Control the focus state of a specific element. You can either set focus on an element (useful for keyboard navigation and form interactions) or remove focus from an element (useful for clearing active states and form validation).

  • browser_press_key

    Simulate pressing a single key on the keyboard. Supports special keys (ArrowLeft, ArrowRight, Enter, Escape, Tab, etc.) and regular characters (a, b, 1, 2, etc.). Useful for navigation, keyboard shortcuts, and triggering key-based interactions.

  • browser_type

    Type text into editable element, replacing any existing content (useful for clearing and filling inputs)

  • browser_navigate_url

    Navigate to a URL

  • browser_navigate_action

    Perform navigation actions using exact values: "back" (go to previous page), "forward" (go to next page), or "reload" (refresh current page)

  • browser_network_requests

    Returns all network requests since loading the page with optional filtering by HTTP method, status code, content type, and URL pattern

  • browser_network_request_details

    Get detailed information about a specific network request using its URL and optionally HTTP method

  • browser_playwright_code

    Execute arbitrary Playwright code directly. This allows for advanced automation tasks that are not covered by other tools. The code should be wrapped in an async function. Example: (async () => { await page.goto("https://example.com"); await page.fill("input[name="search"]", "test"); await page.click("button[type="submit"]"); })()

  • browser_take_screenshot

    Take a screenshot of the current page. You can't perform actions based on the screenshot, use browser_snapshot for actions.

  • browser_snapshot

    Capture accessibility snapshot of the current page to analyze the DOM structure, element roles, attributes, and semantic relationships for accessibility testing and debugging.

  • browser_click

    Perform click actions on a web page, including single clicks, double clicks, and right clicks. Supports different mouse buttons (left, right, middle) and can be used for checking checkboxes, selecting radio buttons, submitting forms, opening context menus, and double-clicking elements

  • browser_drag

    Perform drag and drop operations between two elements on a web page. Supports reordering items in sortable lists, moving cards in kanban boards, dragging files to upload zones, rearranging table rows, and other interactive drag and drop scenarios. Automatically handles mouse events (mousedown, mousemove, mouseup) required for complete drag operations.

  • browser_tab_list

    Retrieve information about all currently open browser tabs, including their URLs, titles, and active status. This tool provides a comprehensive overview of the browser session state.

  • browser_tab_new

    Create a new browser tab and optionally navigate to a specific URL. If no URL is provided, the new tab will remain blank. After creation, automatically captures a page snapshot of the new tab.

  • browser_tab_select

    Switch to a specific browser tab by its index position. After selecting the tab, automatically captures a page snapshot to provide the current state of the selected tab.

  • browser_tab_close

    Close a browser tab by its index position, or close the currently active tab if no index is specified. After closing, automatically captures a page snapshot of the remaining active tab.

  • browser_wait_for

    Wait for text to appear/disappear, element state changes, or a specified time to pass

Use MCP Macaco Playwright MCP with multiple AI models

TypingMind connects MCP tools at the workspace level, so once MCP Macaco Playwright is connected, you can use it with different AI models in TypingMind instead of setting it up separately for each model. This MCP runs locally through the TypingMind MCP connector on your device.

Setup guide to use the local connector

Use this when the MCP server needs access to local files, apps, or private resources on your computer.

1

Open the MCP settings

In TypingMind, go to Settings, Advanced Settings, then Model Context Protocol and choose Setup Connector.

  1. Open TypingMind in your browser.
  2. Click the Settings icon.
  3. Go to Advanced Settings.
  4. Open the Model Context Protocol section.
  5. Click Setup Connector and choose This Device.
TypingMind MCP connector setup screen with This Device selected
2

Run the connector command

Choose This Device, copy the command from TypingMind, and run it in Terminal. Keep the process running while you use MCP.

  1. Copy the setup command shown by TypingMind.
  2. Open Terminal on macOS or Windows Terminal on Windows.
  3. Paste and run the command.
  4. Approve the package install if Terminal asks you to proceed.
  5. Keep the Terminal window running while using MCP tools.
3

Add MCP Macaco Playwright as a server

When the connector status is Ready, click Edit Servers and paste the MCP server configuration.

  1. Wait until the connector status shows Ready.
  2. Click Edit Servers.
  3. Paste the MCP Macaco Playwright MCP server configuration.
  4. Save the server list.
  5. Refresh if you want to confirm the connector is still ready.
TypingMind MCP settings showing active server and Edit Servers button
{
  "mcpServers": {
    "mcp-macaco-playwright": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-macaco-playwright"
      ]
    }
  }
}
4

Use it across models

Save the server list, open Plugins, enable the MCP Macaco Playwright MCP tools, then select any supported AI model in TypingMind and use the tools in chat or assign them to an AI agent.

  1. Open the Plugins page in TypingMind.
  2. Enable the MCP Macaco Playwright MCP tools.
  3. Start a chat and choose the AI model you want to use.
  4. Use the MCP tools in chat or assign them to an AI agent.
  5. Switch to another AI model whenever needed without reconnecting MCP.
TypingMind chat using enabled MCP tools with a selected AI model
Can you use MCP Macaco Playwright to help me with this task?
MCP Macaco Playwright
Sure. I read it.
Here is what I found using MCP Macaco Playwright.

Frequently asked questions

What is the MCP Macaco Playwright MCP server used for?

MCP Macaco Playwright is an MCP server that lets compatible AI clients connect to external tools and context. In TypingMind, you can add this MCP server once and make its tools available in your AI workspace.

Can I use MCP Macaco Playwright MCP with multiple AI models in TypingMind?

Yes. TypingMind connects MCP tools at the workspace level, so you can use MCP Macaco Playwright with different AI models such as Claude, ChatGPT, Gemini, or other models you have configured in TypingMind without setting up the MCP server separately for each model.

Why use MCP Macaco Playwright MCP with TypingMind?

TypingMind is one of the best frontends for LLM chat because it brings multiple AI models, prompts, plugins, AI agents, API keys, and MCP tools into one workspace. With MCP Macaco Playwright connected, you can use its MCP tools across your preferred models while keeping your chat workflow organized in TypingMind.

How do I connect MCP Macaco Playwright MCP to TypingMind?

MCP Macaco Playwright runs through the TypingMind local MCP connector. This is best when the MCP server needs access to local files, desktop apps, command-line tools, or private resources on your computer.

What tools does MCP Macaco Playwright MCP provide in TypingMind?

MCP Macaco Playwright exposes 28 MCP tools that can be enabled from the TypingMind Plugins page and used in chat or assigned to AI agents.

Do I need to share my API keys with TypingMind to use MCP Macaco Playwright MCP?

No. TypingMind is local-first and lets you keep your model providers, API keys, prompts, and MCP configuration under your control. If MCP Macaco Playwright requires authentication, add the required headers, OAuth settings, or local configuration for that MCP server when you create the connection.

Related MCP Servers

View all
firecrawl logo

Firecrawl

firecrawl
OrganizationPopular

The web data API to search, scrape, and interact at scale. 🔥

9.9K
183K
0 tools
View details
ChromeDevTools logo

Chrome DevTools

ChromeDevTools
OrganizationPopular

Chrome DevTools for coding agents

4.4K
52.4K
29 tools
View details
microsoft logo

Playwright Browser Automation

microsoft
OrganizationPopular

Playwright MCP server

3.2K
37.5K
25 tools
View details
hangwin logo

Chrome MCP

hangwin
CommunityPopular

Chrome MCP Server is a Chrome extension-based Model Context Protocol (MCP) server that exposes your Chrome browser functionality to AI assistants like Claude, enabling complex browser automation, content analysis, and semantic search.

1.1K
12.4K
0 tools
View details

Set up your own AI workspace now

Get notified about new features and future giveaways by subscribing to our newsletter 👇