puppeteer

This MCP server provides a comprehensive Puppeteer tool suite you can access via the MCP 2.0-compatible endpoints. It exposes 16 Puppeteer tools such as puppeteer_navigate, puppeteer_screenshot, puppeteer_click, puppeteer_fill, puppeteer_select, puppeteer_hover, puppeteer_evaluate, and advanced mouse tools like puppeteer_mouse_move, puppeteer_mouse_click, puppeteer_mouse_down, puppeteer_mouse_up, puppeteer_mouse_wheel, and puppeteer_mouse_drag. Cookie management tools (puppeteer_get_cookies, puppeteer_set_cookies, puppeteer_delete_cookies) are available for managing authentication state. The server supports multiple transports (HTTP with modern MCP 2025-06-18 streamable transport, and backward-compatible SSE), with API key authentication and session management. To begin, ensure your API key is configured, start the server, and obtain a session via the initialize method on the streamable HTTP transport. You can then call tools by name with the appropriate arguments, for example calling puppeteer_navigate with { "url": "https://example.com" }. Real-time updates can be consumed over SSE, and all requests should include the Bearer token in the Authorization header.

Prerequisites:

• Node.js >= 18.0.0
• npm >= 8.0.0
• Optional: Docker for containerized deployment

Local development and installation steps:

1. Clone the repository

git clone https://github.com/sultannaufal/puppeteer-mcp-server.git
cd puppeteer-mcp-server

2. Install dependencies

npm install

3. Configure environment

cp .env.example .env

Edit .env to set:

• API_KEY=your-secure-api-key-here
• PORT=3000 (or any available port)
• HOST=0.0.0.0 (or your host)

4. Build the project

npm run build

5. Run the server

npm start

If you prefer Docker:

6. Build and run with Docker Compose (as shown in Quick Start)

docker compose up -d

Notes and tips:

• Ensure the API_KEY is kept secret and is provided in the Authorization header for all requests except health checks.
• When using Puppeteer, the server can be configured to skip Chromium download or point to a custom Chromium executable via environment variables (PUPPETEER_SKIP_CHROMIUM_DOWNLOAD, PUPPETEER_EXECUTABLE_PATH).
• For production, consider tuning RATE_LIMIT_MAX, HEALTH_CHECK_PATH, and logging settings (LOG_LEVEL, LOG_FORMAT) according to your needs.
• If you run into browser sandbox issues in certain environments, adjust PUPPETEER_LAUNCH_OPTIONS to include --no-sandbox and --disable-setuid-sandbox as needed.
• Use the streamable HTTP transport for modern MCP 2025-06-18 workflows; you can fall back to SSE for compatibility with older clients.
• The server supports multi-transport and session management; always pass MCP-Session-Id after initialize to subsequent tool calls.