Registry / llm-agents / puppeteer-mcp-server

puppeteer-mcp-server

library0.7.2jsnpmunverified

The `puppeteer-mcp-server` package, currently at version 0.7.2, provides an experimental Model Context Protocol (MCP) server for browser automation, leveraging the Puppeteer library. It offers capabilities such as web page navigation, screenshot capture, form filling, element interaction, and JavaScript execution within a browser environment. A significant feature is its intelligent Chrome tab management, enabling connections to existing active Chrome instances and preserving browser sessions for more efficient and context-aware automation workflows. This project is directly inspired by `@modelcontextprotocol/server-puppeteer` but explores alternative approaches. It operates primarily as a standalone command-line interface (CLI) application, designed for integration with AI agents like Claude Desktop or its VSCode Extension, allowing these agents to perform browser-based actions. Its release cadence is iterative, with recent updates focusing on refactoring and error handling, indicating active development. Due to its pre-1.0 experimental status, users should anticipate potential API adjustments and breaking changes as it evolves, although it is actively maintained.

llm-agents http-networking

npm install puppeteer-mcp-server

github ↗package ↗

INSTALL

IMPORT

SIG · PUPPETEER-MCP-SERV

puppeteer-mcp-server

llm-agentsjavascriptv0.7.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

This quickstart illustrates configuring the MCP server for an AI agent (like Claude) using `npx`, and a programmatic TypeScript example of launching the server via `child_process`.

```json { "mcpServers": { "puppeteer": { "command": "npx", "args": ["-y", "puppeteer-mcp-server", "--port", "8080"], "env": {} } } } ``` ```typescript // To programmatically run the server, a common approach for development or embedding // would be to use a child process or a package.json script. // This example demonstrates running it via Node.js CLI. // Ensure 'dist/index.js' exists after building the project (npm run build). import { exec } from 'child_process'; const serverProcess = exec('node dist/index.js --port 8080', { cwd: '/path/to/your/puppeteer-mcp-server' }); serverProcess.stdout?.on('data', (data) => { console.log(`Server Output: ${data}`); }); serverProcess.stderr?.on('data', (data) => { console.error(`Server Error: ${data}`); }); serverProcess.on('close', (code) => { console.log(`Server process exited with code ${code}`); }); console.log('Puppeteer MCP Server started via child process.'); // In a real application, you'd manage the lifecycle, e.g., stop on app exit. // serverProcess.kill(); // To stop the server programmatically ```

puppeteer-mcp-server --version

Debug

Known issues

breakingAs an 'experimental' package with a version less than 1.0.0, `puppeteer-mcp-server` may introduce breaking changes in minor or even patch releases. APIs and internal structures are subject to change without strict adherence to semantic versioning until a stable 1.0.0 release.

fix

Regularly review the project's GitHub repository and release notes for updates. Pin specific versions in production environments to prevent unexpected breaking changes.

affects: <1.0.0

gotchaThe server's core functionality relies on Puppeteer, which in turn requires a compatible browser (Chromium, Chrome, or Edge) to be available on the system. If Puppeteer cannot find a browser, the server will fail to initialize or execute browser automation tasks.

fix

Ensure that `puppeteer` is correctly installed (often handled by `npm install`) which typically downloads Chromium. For headless environments or specific browser paths, configure Puppeteer's executable path or install necessary browser dependencies (e.g., `sudo apt install chromium`).

affects: >=0.1.0

gotchaConfiguring `puppeteer-mcp-server` for use with external applications like Claude Desktop or VSCode Extension requires precise JSON configuration paths and commands. Incorrect paths, arguments, or environment variables in the `mcpServers` configuration can lead to the server failing to launch or connect.

fix

Double-check the `command` and `args` in the `mcpServers` JSON configuration. For source installations, ensure `node` and the correct `dist/index.js` path are specified. Verify that `NODE_OPTIONS: "--experimental-modules"` is included if running from source with ES modules.

affects: >=0.1.0

Errors

Common errors & fixes

command not found: puppeteer-mcp-server

The `puppeteer-mcp-server` executable is not in the system's PATH, or `npx` is not being used to invoke it directly from the `node_modules` bin.

fix

If installed globally, verify `npm root -g` contains it. If locally, use `npx puppeteer-mcp-server` or add `$(npm bin)` to your PATH. Alternatively, configure the calling application to use `npx -y puppeteer-mcp-server`.

Error: Could not find Chromium (or Chrome/Edge/...) at ...

Puppeteer, a core dependency, failed to locate a suitable browser executable on the system to launch or connect to.

fix

Ensure Puppeteer's default Chromium is downloaded by running `npm install` in the project directory. If using a custom browser, verify its path and permissions. For Docker or server environments, ensure browser dependencies are installed.

TypeError: Cannot read properties of undefined (reading 'on')

This generic error often indicates an issue within the server's internal logic, possibly related to an uninitialized object or a failed connection to the browser or MCP client.

fix

Check the server's console output for more specific preceding errors. Ensure all configuration files are correct and that Puppeteer can launch or connect to a browser successfully. Update to the latest version of `puppeteer-mcp-server` as this might be a bug fix.

Upgrade

Version history

0.7.2latest on npm

Audit

Dependencies

puppeteerrequiredCore browser automation engine required for all server operations.

Agent activity

23 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/merajmehrabi/puppeteer-mcp-server ↗

packagehttps://www.npmjs.com/package/puppeteer-mcp-server ↗