djannot/puppeteer-vision-mcp

This Model Context Protocol (MCP) server provides a tool for scraping webpages and converting them to markdown format using Puppeteer, Readability, and Turndown. It features AI-driven interaction capabilities to handle cookies, captchas, and other interactive elements automatically.
**Now easily runnable via npx!**
Features
- Scrapes webpages using Puppeteer with stealth mode
- Uses AI-powered interaction to automatically handle:
- Cookie consent banners
- CAPTCHAs
- Newsletter or subscription prompts
- Paywalls and login walls
- Age verification prompts
- Interstitial ads
- Any other interactive elements blocking content
- Extracts main content with Mozilla's Readability
- Converts HTML to well-formatted Markdown
- Special handling for code blocks, tables, and other structured content
- Accessible via the Model Context Protocol
- Option to view browser interaction in real-time by disabling headless mode
- Easily consumable as an npx package.
Quick Start with NPX
The recommended way to use this server is via npx, which ensures you're running the latest version without needing to clone or manually install.
1. **Prerequisites:** Ensure you have Node.js and npm installed.
2. **Environment Setup:**
The server requires an OPENAI_API_KEY. You can provide this and other optional configurations in two ways:
* **.env file:** Create a .env file in the directory where you will run the npx command.
* **Shell Environment Variables:** Export the variables in your terminal session.
**Example .env file or shell exports:**
3. **Run the Server:**
Open your terminal and run:
* The -y flag automatically confirms any prompts from npx.
* This command will download (if not already cached) and execute the server.
* By default, it starts in stdio mode. Set TRANSPORT_TYPE=sse or TRANSPORT_TYPE=http for HTTP server modes.
Using as an MCP Tool with NPX
This server is designed to be integrated as a tool within an MCP-compatible LLM orchestrator. Here's an example configuration snippet:
When configured this way, the MCP orchestrator will manage the lifecycle of the puppeteer-vision-mcp-server process.
Environment Configuration Details
Regardless of how you run the server (NPX or local development), it uses the following environment variables:
- **OPENAI_API_KEY**: (Required) Your API key for accessing the vision model.
- **VISION_MODEL**: (Optional) The model to use for vision analysis.
- Default: gpt-4.1
- Can be any model with vision capabilities.
- **API_BASE_URL**: (Optional) Custom API endpoint URL.
- Use this to connect to alternative OpenAI-compatible providers (e.g., Together.ai, Groq, Anthropic, local deployments).
- **TRANSPORT_TYPE**: (Optional) The transport protocol to use.
- Options: stdio (default), sse, http
- stdio: Direct process communication (recommended for most use cases)
- sse: Server-Sent Events over HTTP (legacy mode)
- http: Streamable HTTP transport with session management
- **USE_SSE**: (Optional, deprecated) Set to true to enable SSE mode over HTTP.
- Deprecated: Use TRANSPORT_TYPE=sse instead.
- **PORT**: (Optional) The port for the HTTP server in SSE or HTTP mode.
- Default: 3001.
- **DISABLE_HEADLESS**: (Optional) Set to true to run the browser in visible mode.
- Default: false (browser runs in headless mode).
Communication Modes
The server supports three communication modes: