ratiofu/mcp-puppeteer
If you are the rightful owner of mcp-puppeteer and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
A simple MCP Server for controlling Chrome via Puppeteer.
Puppeteer MCP Server
A Model Context Protocol (MCP) server that provides browser automation capabilities through Puppeteer with intelligent browser management. This server enables AI assistants to control Chromium browsers, take screenshots, extract content, and interact with web pages.
✨ The key difference of this implementation compared to others is that it enables access to the raw DOM content of the page and the console!
MCP Client Configuration
Add this to your MCP client configuration:
{
"mcpServers": {
"puppeteer": {
"command": "npx",
"args": [
"-y",
"@ratiofu/mcp-puppeteer"
]
}
}
}
Notes:
- Some MCP clients support additional server configuration options. Consult your MCP client's documentation for advanced configuration settings.
- If you're using other Puppeteer-based MCP servers, consider using a unique name like
"puppeteer-ratiofu"to avoid conflicts. Only run one Puppeteer MCP server at a time, and update any local agent guidance accordingly if you change the server name.
Available Tools
navigate: Navigate to URLslist_tab_urls: List all open tab URLsclick: Click elements using CSS selectorstake_screenshot: Capture page screenshotsget_html: Extract page HTML contentget_console: Retrieve browser console output
Prerequisites
You need Chromium running with remote debugging enabled:
macOS
open -a "Chromium" --args --remote-debugging-port=9222
Linux
chromium --remote-debugging-port=9222
Windows
chromium --remote-debugging-port=9222
How It Works
The server automatically downloads and runs via npx when your MCP client needs it. No manual installation required! It uses Chromium's remote debugging protocol to control your browser.
Troubleshooting
Chromium Connection Issues
Error: "Could not connect to Chromium"
Ensure you actually started Chromium (see above).
You can verify Chromium is ready by opening http://localhost:9222/json in your browser.
MCP Client Issues
Server not responding:
- Ensure Chromium is running with debug port (see Prerequisites section)
- Check your MCP client configuration matches the examples
- Verify Node.js 22+ is installed (
node --version)
Need to test manually?
echo '{}' | npx @ratiofu/mcp-puppeteer
Development
For local development:
git clone https://github.com/ratiofu/mcp-puppeteer
cd mcp-puppeteer
pnpm install
pnpm run build
pnpm start
Development Scripts
pnpm run dev # Auto-rebuild and restart
pnpm run test # Run unit tests
pnpm run test:coverage # Run tests with coverage
pnpm run quality # Full quality pipeline (typecheck + lint + test coverage)
pnpm run lint # Check code with Biome linter
pnpm run lint:fix # Auto-fix linting and formatting issues
pnpm run inspector # Test with MCP Inspector
Architecture
- Pipe Transport: Direct stdin/stdout communication with MCP clients
- Puppeteer Core: Browser automation without bundled browsers
- Automatic Cleanup: Browser resources cleaned up on process exit
