What is the Puppeteer MCP server?
The Puppeteer MCP server by merajmehrabi gives an AI agent eight tools for browser automation with Puppeteer: navigate, screenshot, click, fill, select, hover, evaluate JavaScript and connect to an open Chrome tab. You run it with npx -y puppeteer-mcp-server. The README calls it experimental.
It is a Model Context Protocol server that wraps Puppeteer so an AI agent can control a browser. The README describes it as an experimental implementation inspired by the reference Puppeteer server in the modelcontextprotocol servers repo, with its own approach to connecting to browsers.
By default it launches a new browser instance. Its distinguishing feature is active tab mode: start Chrome with remote debugging on, and the agent can attach to a tab you already have open without closing your browser.
What it changes in your workflow
- The agent can load a page, click a selector, fill an input and screenshot the result, so it checks its own front end changes.
- Active tab mode lets it work in a page where you are already signed in, because it connects to your running Chrome.
- puppeteer_evaluate runs JavaScript in the page, which helps with reading values the page computes.
- Each call returns success or failure with an error message, and everything is also written to log files.
How it runs
| Puppeteer MCP server | |
|---|---|
| Where it runs | On your machine, as a Node process the client starts |
| Transport | stdio |
| Install | npx -y puppeteer-mcp-server, or npm install -g puppeteer-mcp-server |
| Browser | Puppeteer's browser, or your own Chrome with remote debugging on port 9222 |
| Account or key | None |
Who it is for
Best for
- Developers who already know Puppeteer and want selector-based control from an agent.
- Quick checks inside an existing Chrome session, such as a page behind a login you completed yourself.
- Small scripts where eight simple tools are enough.
Not for
- Cross-browser testing. The README describes Puppeteer and Chrome only, so use Chrome DevTools MCP or a Playwright based server for other needs.
- Heavily maintained tooling. The repo's last push was in March 2025, and the README labels the project experimental.
- Reading pages by structure. There is no snapshot tool; the agent targets CSS selectors you or it supply.
Use it with UiChemy
Use the server to preview a page you built with UiChemy. Composer and Figma to WordPress produce pages in Elementor or Gutenberg; the agent can open the live URL, click through the layout and capture screenshots. Click Get Started on uichemy.com to try the WordPress side.
Connect Puppeteer MCP Server: Browser Control for AI Agents to your AI client
npx -y puppeteer-mcp-serverPick an install route
Run it with npx as above, install globally with
npm install -g puppeteer-mcp-server, or clone the repo, run npm install, npm run build and npm start.Add the config
Put the entry in your MCP client's settings. The README shows the Claude Desktop file and the Cline settings file, and uses the same entry shape for both.
Restart the client
Reload your client so it starts the server and lists the eight puppeteer tools.
Optional: attach to Chrome
Close Chrome fully, relaunch it with --remote-debugging-port=9222, open your page, then ask the agent to call puppeteer_connect_active_tab.
Try a prompt
Ask the agent to navigate to your local site and take a screenshot named home.
Client configuration
{
"mcpServers": {
"puppeteer": {
"command": "npx",
"args": ["-y", "puppeteer-mcp-server"],
"env": {}
}
}
}Endpoints and ports
npx -y puppeteer-mcp-serverStarts the server over stdio.9222Default port for puppeteer_connect_active_tab. Can be changed with the debugPort argument.logs/mcp-puppeteer-YYYY-MM-DD.logDaily rotation, 20MB per file, 14 days kept.What you can do with it
- Active tab modeConnects to a Chrome tab you opened yourself and leaves your browser running when the session ends.
- New browser by defaultWithout extra setup, the server launches its own browser instance for the agent.
- Eight focused toolsNavigate, screenshot, click, fill, select, hover, evaluate and connect cover the common page actions.
- Screenshot sizingScreenshots take a name, an optional selector and optional width and height.
- File loggingWinston logs in the logs folder rotate daily, cap at 20MB per file and keep 14 days.
- Clear errorsFailures such as bad selectors, connection problems and script errors come back as messages the agent can act on.
- Security remindersThe README advises remote debugging only on trusted networks, with a unique port that is closed when unused.
Tools it exposes
puppeteer_connect_active_tab
Connects to an existing Chrome instance with remote debugging. Optional targetUrl and debugPort.
puppeteer_navigate
Navigates to a URL.
puppeteer_screenshot
Screenshots the page or an element. Needs a name; optional selector, width and height (default 800 by 600).
puppeteer_click
Clicks the element matching a CSS selector.
puppeteer_fill
Fills an input field, given a selector and a value.
puppeteer_select
Chooses an option in a select element.
puppeteer_hover
Hovers over an element.
puppeteer_evaluate
Executes JavaScript in the browser console.
Frequently asked questions
What is the Puppeteer MCP server?
It is an MCP server that wraps Puppeteer so an AI agent can navigate pages, click, fill forms, hover, take screenshots and run JavaScript. This one is by merajmehrabi, and its README describes it as an experimental implementation inspired by the reference Puppeteer server.
How do I install the Puppeteer MCP server?
Run npx -y puppeteer-mcp-server from your MCP client config, or install globally with npm install -g puppeteer-mcp-server. You can also clone the repo, run npm install and npm run build. Then restart the client so the tools appear.
Can the Puppeteer MCP server use my open Chrome?
Yes, through active tab mode. Close Chrome, relaunch it with --remote-debugging-port=9222, open your page and call puppeteer_connect_active_tab. The README says it preserves your Chrome instance and connects to non-extension tabs.
Which tools does the Puppeteer MCP server have?
Eight: puppeteer_connect_active_tab, puppeteer_navigate, puppeteer_screenshot, puppeteer_click, puppeteer_fill, puppeteer_select, puppeteer_hover and puppeteer_evaluate. Click, fill, select and hover take a CSS selector, while screenshot takes a required name and optional selector, width and height. The connect tool takes an optional target URL and debug port.
Is the Puppeteer MCP server still maintained?
The repo's latest push is March 2025 and its README calls the project an experimental implementation. If you need frequent updates or more browsers, compare it with agnt MCP or Chrome DevTools MCP before you commit to it.
Is it safe to enable remote debugging?
The README advises enabling it only on trusted networks, using a unique port, closing the port when not in use and never exposing it to public networks. Anything that can reach the port can control your Chrome.
Where does the Puppeteer MCP server write logs?
It writes to a logs folder using files named mcp-puppeteer-YYYY-MM-DD.log. The README says they rotate daily, hold at most 20MB each, keep 14 days and compress old files. Logs include navigation, tool results and browser console output.
Puppeteer MCP or Chrome DevTools MCP?
Both focus on Chrome. This server is a small set of selector-based tools you can read in one sitting, while Chrome DevTools MCP is built around DevTools style inspection. Choose by whether you need simple page actions or deeper debugging.


