Puppeteer
Self-hosted Puppeteer MCP server with remote SSE access, API key authentication, and Docker deployment. Complete tool suite for browser automation via Model Context Protocol.
What is Puppeteer?
Puppeteer is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to self-hosted puppeteer mcp server with remote sse access, api key authentication, and docker deployment. complete tool suite for browser automation via model context protocol.
Self-hosted Puppeteer MCP server with remote SSE access, API key authentication, and Docker deployment. Complete tool suite for browser automation via Model Context Protocol.
This server falls under the Browser Automation category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- puppeteer_navigate
- puppeteer_screenshot
- puppeteer_click
- puppeteer_fill
- puppeteer_select
Use Cases
Maintainer
Works with
Installation
NPM
npx -y @modelcontextprotocol/server-puppeteerManual Installation
npx -y @modelcontextprotocol/server-puppeteerConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use Puppeteer
This Puppeteer MCP Server provides a self-hosted, remotely accessible browser automation gateway built on top of Puppeteer, exposing 16 tools for navigation, screenshot capture, form interaction, JavaScript execution, cookie management, and advanced mouse control. It runs as a Docker container with API key authentication and supports both Streamable HTTP (MCP 2025-06-18) and legacy SSE transports, making it suitable for teams that need shared browser automation infrastructure accessible from multiple Claude instances or CI pipelines rather than a locally installed browser.
Prerequisites
- Docker and Docker Compose installed on your server
- Node.js 18+ if running without Docker
- An MCP-compatible client such as Claude Desktop or Cursor
- A securely generated API key for bearer token authentication (the server requires one — it has no default)
Clone the repository
Clone the puppeteer-mcp-server repository to your machine or server.
git clone https://github.com/sultannaufal/puppeteer-mcp-server.git
cd puppeteer-mcp-serverCreate the .env file with your API key
Generate a secure random API key and write it to a .env file. This key will be required for all MCP connections to the server.
echo "API_KEY=$(openssl rand -hex 32)" > .env
# Also optionally set:
# PORT=3000
# BROWSER_TIMEOUT=30000
# LOG_LEVEL=infoStart the server with Docker Compose
Build and start the container. The server binds to the configured PORT (default 3000) and launches a headless Chromium instance inside the container.
docker compose --env-file .env up -dVerify the server is running
Check the container logs to confirm the MCP server started and Chromium initialized correctly.
docker compose logs -fAdd the server to your MCP client configuration
Register the running server endpoint in claude_desktop_config.json. Use the Streamable HTTP transport pointing to your server's address with the API key as the bearer token.
Puppeteer Examples
Client configuration
Claude Desktop configuration connecting to the self-hosted Puppeteer MCP server over HTTP with bearer token authentication. Replace the API key and host with your actual values.
{
"mcpServers": {
"puppeteer": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-puppeteer"],
"env": {
"API_KEY": "your_secure_api_key_here",
"PORT": "3000",
"BROWSER_TIMEOUT": "30000"
}
}
}
}Prompts to try
Use Puppeteer tools to automate browser tasks, capture screenshots, and interact with web applications.
- "Navigate to https://example.com and take a screenshot."
- "Fill the login form at https://app.example.com with username '[email protected]' and submit it."
- "Take a screenshot of https://dashboard.example.com after logging in with the stored session cookie."
- "Execute this JavaScript on the current page and return the result: document.querySelectorAll('h1').length"
- "Drag the element with id 'card-1' and drop it onto the element with id 'column-2'."
- "Get all cookies for the current session and show me the authentication tokens."Troubleshooting Puppeteer
Container starts but Chromium crashes immediately
Headless Chromium inside Docker requires the --no-sandbox flag and sufficient shared memory. Add '--shm-size=2gb' to your docker run command or add 'shm_size: 2gb' under the service in docker-compose.yml. Also ensure the container has at least 512MB of RAM available.
Authentication errors: '401 Unauthorized' from the MCP server
The API_KEY environment variable in your MCP client config must exactly match the API_KEY set in the server's .env file. Check for leading/trailing spaces or newline characters if copying the key manually.
Timeouts on slow pages or complex interactions
Increase BROWSER_TIMEOUT in the server's .env file (default is 30000ms = 30 seconds). For JavaScript-heavy SPAs, add explicit waits in your prompts: ask Claude to 'wait for the network to be idle' before taking a screenshot.
Frequently Asked Questions about Puppeteer
What is Puppeteer?
Puppeteer is a Model Context Protocol (MCP) server that self-hosted puppeteer mcp server with remote sse access, api key authentication, and docker deployment. complete tool suite for browser automation via model context protocol. It connects AI assistants to external tools and data sources through a standardized interface.
How do I install Puppeteer?
Install via npm with the command: npx -y @modelcontextprotocol/server-puppeteer. Then add the server configuration to your AI client's JSON config file (e.g., claude_desktop_config.json or .cursor/mcp.json).
Which AI clients work with Puppeteer?
Puppeteer works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is Puppeteer free to use?
Yes, Puppeteer is open source and available under the MIT license. You can use it freely in both personal and commercial projects.
Puppeteer Alternatives — Similar Browser Automation Servers
Looking for alternatives to Puppeteer? Here are other popular browser automation servers you can use with Claude, Cursor, and VS Code.
Chrome DevTools MCP
★ 40.6kAI-powered Chrome automation server with natural language element detection. Control Chrome browser through MCP protocol for testing, debugging, and performance analysis. Features 91% accuracy in element location, works with free AI models, and suppo
UI TARS Desktop
★ 34.9k📇 🏠 - Browser automation capabilities using Puppeteer, both support local and remote browser connection.
Playwright
★ 32.8kA production-ready browser automation server that enables AI assistants to interact with web pages using tools for navigation, element interaction, and data extraction. It features a built-in Inspector UI and robust crash recovery for reliable automa
Page Agent
★ 18.0kJavaScript in-page GUI agent. Control web interfaces with natural language.
Chrome
★ 11.7kAn extension-based MCP server that enables AI assistants to control your browser, leveraging existing sessions and login states for automation and content analysis. It provides over 20 tools for semantic tab search, interactive element manipulation,
LAMDA
★ 7.8kThe most powerful Android RPA agent framework, next generation mobile automation.
Browse More Browser Automation MCP Servers
Explore all browser automation servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up Puppeteer in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use Puppeteer?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.