puppeteer

This MCP server exposes browser automation capabilities via Puppeteer. It can launch a new browser instance by default or connect to an existing Chrome window (active tab mode) when remote debugging is enabled. Available tools let you navigate pages, take screenshots, click elements, fill forms, select options, hover elements, and execute JavaScript within the page. A key feature is smart Chrome tab management, which preserves existing Chrome instances and can connect to non-extension tabs, giving you flexible control over browser automation without forcing a fresh browser every time.

To use the server, first run the MCP server (puppeteer-mcp-server) via your preferred installation method (global npm install or npx). Once the server is running, you can invoke the provided tools through your MCP client, calling tools like puppeteer_connect_active_tab to attach to an existing Chrome with remote debugging enabled, or puppeteer_navigate to direct the browser to a URL. Other tool endpoints include puppeteer_screenshot, puppeteer_click, puppeteer_fill, puppeteer_select, puppeteer_hover, and puppeteer_evaluate to perform a wide range of browser automation tasks. Each tool returns a structured result indicating success, data, or a detailed error message.

Prerequisites:

• Node.js and npm installed on your system
• Access to the command line/terminal

Option A: Install from npm (globally) and run

1. Install globally:

npm install -g puppeteer-mcp-server

2. Start the server:

puppeteer-mcp-server

Option B: Run directly with npx (no installation)

1. Run the server using npx:

npx puppeteer-mcp-server

Option C: Install from source (developing or contributing)

1. Clone the repository or download the source code
2. Install dependencies:

npm install

3. Build the project (if required by the setup):

npm run build

4. Run the server:

npm start

Notes:

• When using from source, you may need to adjust NODE_OPTIONS for ES modules as described in the configuration examples in the README.

Tips and considerations:

• Security: When enabling remote debugging for connecting to existing Chrome tabs, ensure the debugging port is not exposed publicly and is restricted to trusted networks.
• Logging: The server logs to the logs/ directory with daily rotated files. Review logs for detailed browser operations, tool usage, and errors.
• Environment variables: You might need to set NODE_OPTIONS=--experimental-modules when running from source in certain setups.
• Configuration: The MCP settings examples show how to declare the puppeteer MCP server in Claude Desktop and Claude VSCode Extension configurations. You can use either the npm-installed command, or npx, or a node path to a local build when running from source.
• Error handling: Tools return structured success/failure information along with descriptive error messages and stack traces where available. Use these details to diagnose issues with selectors, navigation, or JavaScript execution.