Puppeteer MCP: Let AI automatically simulate real user operations and realize complex browser interactions!

Almost every developer will encounter a series of complex interactive simulation scenarios such as web page testing and data crawling when using a browser.

This involves browser automation, which can help us developers save a lot of time and energy, so browser automation has become an indispensable tool.

Puppeteer is such an efficient and easy-to-use browser automation tool. Let’s talk about this magical thing!

What can Puppeteer do?

Let’s put it this way, most of the operations we perform manually in the browser can be  completed using Puppeteer. Isn’t that amazing?

What is Puppeteer MCP?

Puppeteer MCP is a server based on Model Context Protocol that allows us developers to easily interact with web pages by providing browser automation capabilities.

Taking screenshots and executing JavaScript in a real browser environment, in other words, Puppeteer MCP is a powerful tool.

It encapsulates the browser's operating capabilities into a set of simple interfaces, and we developers can implement complex browser automation tasks simply by calling these interfaces.

The core of Puppeteer MCP is based on Puppeteer, a Node.js library developed by Google to control headless Chrome or Chromium browsers.

Through the MCP protocol, Puppeteer MCP further expands the functionality of Puppeteer, enabling it to be more flexibly integrated with the Large Language Model (LLM) to achieve more intelligent automated operations.

What are the core functions of Puppeteer MCP?

Puppeteer MCP undoubtedly provides us developers with a series of powerful tools and resources. The following are its main functional modules:

1.  Browser navigation and interaction: Puppeteer MCP provides puppeteer_navigate Tool that makes it easy to navigate to any URL. We developers only need to provide the target URL and let the browser automatically load the page.

In addition, we can also launchOptionsParameters customize the browser's startup options, such as whether to run in headless mode, set the browser window size, etc.

{ "url": "https://example.com", "launchOptions": { "headless": false, "defaultViewport": {"width": 1280, "height": 720} }}

pass puppeteer_click and puppeteer_hover Tools allow developers to simulate user clicks and hover operations on the page. These tools locate elements through CSS selectors to ensure the accuracy of operations.

{ "selector": "#submit-button"}

2.  Form filling and selection: Puppeteer MCP providespuppeteer_fill and puppeteer_select Tools for filling in input fields and selecting options in drop-down menus. These tools also locate elements using CSS selectors and fill in or select the specified value.

{ "selector": "#username", "value": "test_user"}

3.  Screen capture and monitoring: Puppeteer MCP puppeteer_screenshot The tool can capture a screenshot of the entire page or a specific element. We just need to provide a name for the screenshot and an optional CSS selector to save the screenshot.

{ "name": "screenshot1", "selector": "#content", "width": 800, "height": 600}

In addition, Puppeteer MCP also provides console log monitoring function. console://logs Resources, we can get the output information of the browser console in real time, so as to better debug and monitor the automation tasks.

4.  JavaScript execution: via puppeteer_evaluate Tools, developers can execute arbitrary JavaScript code in the browser console. This enables Puppeteer MCP to handle complex web page interactions and dynamic content.

{ "script": "document.querySelector('#username').value = 'test_user';"}

Puppeteer MCP also provides a high degree of flexibility and supports customizing browser behavior through environment variables or tool call parameters.

For example, you can set PUPPETEER_LAUNCH_OPTIONS Environment variables to adjust the browser startup options.

How to use Puppeteer MCP?

The configuration of Puppeteer MCP is not complicated. Here is the Claude Desktop configuration using the Puppeteer server:

Docker

Note that  the Docker implementation will use headless Chromium, while the NPX version will open a browser window.

{ "mcpServers": { "puppeteer": { "command": "docker", "args": ["run", "-i", "--rm", "--init", "-e", "DOCKER_CONTAINER=true", "mcp/puppeteer"] } }}

NPX

{ "mcpServers": { "puppeteer": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-puppeteer"] } }}

Boot Options

We can customize Puppeteer's browser behavior in two ways:

Environment variables : configured in MCP env Set in parameters PUPPETEER_LAUNCH_OPTIONS, the value is a JSON-encoded string:

{ "mcpServers": { "mcp-puppeteer": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-puppeteer"], "env": { "PUPPETEER_LAUNCH_OPTIONS": "{ \"headless\": false, \"executablePath\": \"C:/Program Files/Google/Chrome/Application/chrome.exe\", \"args\": [] }", "ALLOW_DANGEROUS": "true" } } }}

Tool call parameters : launchOptions and allowDangerous Parameter passing

{ "url": "https://example.com", "launchOptions": { "headless": false, "defaultViewport": {"width": 1280, "height": 720} }}

Build: Docker Build:

docker build -t mcp/puppeteer -f src/puppeteer/Dockerfile .

Above we have completed the configuration of Puppeteer MCP. Here are some common tools of Puppeteer MCP:

• puppeteer_navigate

• url
   (string, required): The URL to navigate to.
• launchOptions
   (object, optional): PuppeteerJS startup options. Defaults to null. If changed and not null, the browser will restart. Example:{ headless: true, args: ['--user-data-dir="C:/Data"'] }
• allowDangerous
   (boolean, optional): Allows dangerous startup options that reduce security. When false, --no-sandbox,--disable-web-security Such dangerous parameters will throw an error. Defaults to false.
• Navigate to any URL in your browser
• enter:

• puppeteer_screenshot

• name
   (string, required): The name of the screenshot
• selector
   (string, optional): CSS selector of the element to be intercepted
• width
   (number, optional, default: 800): Screenshot width
• height
   (number, optional, default: 600): Screenshot height
• Capture screenshots of entire pages or specific elements
• enter:

• puppeteer_click

• Click on an element on the page
• enter:selector (string): CSS selector of the element to click

• puppeteer_hover

• Hovering over elements on the page
• enter:selector (string): CSS selector of the element to hover

• puppeteer_fill

• selector
   (string): CSS selector for the input field
• value
   (string): The value to be filled in
• Fill in the input fields
• enter:

• puppeteer_select

• selector
   (string): CSS selector of the element to select
• value
   (string): The value to select
• Select elements with the SELECT tag
• enter:

• puppeteer_evaluate

• Execute JavaScript in the browser console
• enter:script (string): JavaScript code to execute

Last words

Puppeteer MCP is a powerful and easy-to-use browser automation tool that not only provides us with rich automation functions, but also has high flexibility and scalability.

Whether it's web page testing, data crawling, or automation tasks, Puppeteer MCP can easily handle it. If you are looking for an efficient browser automation tool, Puppeteer MCP is definitely worth a try!