Mcp-Puppeteer

This MCP server exposes browser automation capabilities powered by Puppeteer. It enables LLMs to interact with real web pages by navigating, clicking, filling forms, taking screenshots, and executing JavaScript within a headful or headless browser depending on the deployment mode. The server provides a set of tools: puppeteer_navigate to open URLs; puppeteer_click to click elements via CSS selectors; puppeteer_hover to hover elements; puppeteer_fill to type into inputs; puppeteer_select to choose options from select elements; puppeteer_screenshot to capture full-page or element-specific screenshots; and puppeteer_evaluate to run JavaScript in the page context. You can also access two resource types: console://logs to monitor browser console output and screenshot://<name> to retrieve PNG screenshots by name. These capabilities are useful for testing, data gathering, or guiding an LLM through interacting with live web content.

To use the tools, send requests that specify the tool name and the required inputs (e.g., url for navigate, selector for click or fill, and optional parameters like name, width, height for screenshots). The server will perform the actions in a real browser environment and return results such as console logs or captured screenshots. This enables automated web interactions and evaluation with live page behavior, making it easier to reason about dynamic content and client-side logic during model evaluation or task completion.

Prerequisites:

• Docker (recommended for the docker-based deployment) or Node.js with npm (for NPX usage)
• Access to the internet to pull the necessary images or packages

Option A: Docker deployment

1. Ensure Docker is installed and running.
2. Build or pull the MCP Puppeteer image if needed (the README suggests using mcp/puppeteer for the container): docker pull mcp/puppeteer
3. Run the container with the provided configuration (example from README): docker run -i --rm --init -e DOCKER_CONTAINER=true mcp/puppeteer

Option B: NPX deployment

1. Install Node.js (recommended version supporting NPX) and npm.
2. Use NPX to run the server directly without installation: npx -y @modelcontextprotocol/server-puppeteer
3. The NPX command will fetch and run the puppeteer server in your environment.

Notes:

• If you use the Docker approach, you may need to map ports or configure networking depending on your environment. The README examples do not specify port mappings, so adjust as needed for your setup.

Tips and common issues:

• When using the Docker option, DOCKER_CONTAINER=true is passed as an environment variable; ensure this aligns with your runtime needs or adjust the var accordingly.
• Puppeteer runs in headless mode by default in many container setups; if you need an interactive window, use the NPX/development mode as described in the README.
• The server exposes navigation, interaction, and evaluation capabilities. For robust automation, combine puppeteer_navigate with explicit waiting for selectors or network Idle states to ensure elements are ready before actions.
• For screenshots, you can specify name, and optional selector and dimensions. If you omit name, ensure your workflow captures a meaningful name for retrieval from screenshot://<name>.
• The console logs are useful for debugging page scripts. Ensure your client handles potentially large log streams.
• If you encounter CORS or CSP errors on some pages, these are browser policy-related and may require additional handling within the Puppeteer script.