webpage-screenshot-mcp

Purpose

Webpage Screenshot MCP is an MCP (Model Context Protocol) server that provides webpage screenshot capabilities for AI agents, enabling Agents to visually verify applications and view development progress through screenshots when generating Web applications.

Main Capabilities

• Full-page screenshots: Capture the entire webpage or only the current viewport.
• Element screenshots: Use CSS selectors to locate and capture specific elements.
• Multiple formats: Supports PNG, JPEG, and WebP formats.
• Customizable options: You can set viewport dimensions, image quality, wait conditions, and delay time.
• Base64 encoding: Screenshots are returned as Base64-encoded images for easy integration.
• Authentication support: Supports manual login and Cookie persistence.
• Default browser integration: You can use the system default browser for a more natural experience.
• Session persistence: Keeps the browser session open to support multi-step workflows.

Usage

Quick Start (Claude Desktop extension)

Drag and drop the generated screenshot-webpage-mcp.dxt file into Claude Desktop to install it automatically.

Manual installation

Install and build the MCP from source: This MCP server is built with TypeScript and compiled to JavaScript; the dist folder contains the compiled JavaScript files.

Add to Claude or Cursor

• Claude Desktop: Go to Settings > Developer, click "Edit Config", and add the following:

  "webpage-screenshot" : { "command" : " node " , "args" : [ " ~/path/to/webpage-screenshot-mcp/dist/index.js " ] }
  

  Save and reload Claude.
• Cursor: Open Cursor, go to Cursor Settings > MCP, click "Add new global MCP server", add the corresponding configuration, save, and reload Cursor.

Provided tools

1. login-and-wait: Opens a webpage in a visible browser window for manual login, waits for the user to complete login, and then saves Cookies.
   • url(required): The URL of the login page
   • waitMinutes(optional): The maximum number of minutes to wait for login, default 5
   • successIndicator(optional): A CSS selector or URL pattern indicating successful login
   • useDefaultBrowser(optional): Whether to use the system default browser, default true
2. screenshot-page: Takes a screenshot of the given URL and returns it as a Base64-encoded image.
   • url(required): The URL of the webpage to screenshot
   • fullPage(optional): Whether to capture the full page or only the viewport, default true
   • width(optional): Viewport width (pixels), default 1920
   • height(optional): Viewport height (pixels), default 1080
   • format(optional): Image format, "png", "jpeg", or "webp", default "png"
   • quality(optional): Image quality (0-100), only applies to jpeg and webp
   • waitFor(optional): When the page is considered loaded, "load", "domcontentloaded", "networkidle0", or "networkidle2", default "networkidle2"
   • delay(optional): Additional delay in milliseconds after page load, default 0
   • useSavedAuth(optional): Whether to use Cookies saved from a previous login, default true
   • reuseAuthPage(optional): Whether to use an existing authenticated page, default false
   • useDefaultBrowser(optional): Whether to use the system default browser, default false
   • visibleBrowser(optional): Whether to show the browser window, default false
3. screenshot-element: Uses a CSS selector to capture a specific element on a webpage.
   • url(required): Webpage URL
   • selector(Required): CSS selector of the element to screenshot
   • waitForSelector(Optional): Whether to wait for the selector to appear, default true
   • padding(Optional): Padding in pixels around the element, default 0
4. clear-auth-cookies: Clear saved authentication cookies for a specific domain or all domains.
   • url(Optional): The domain URL whose cookies should be cleared. If not provided, all cookies are cleared.

Use Cases

• During AI-assisted web development, let the agent inspect page rendering and layout via screenshots.
• Screenshot protected pages that require login: through a manual login phase, open the default browser, complete login and save cookies, then screenshot using the saved session.
• Scenarios that require complex interaction with web pages or multi-step workflows.
• Test in the same browser environment as the user (leveraging existing browser sessions, extensions, and cookies).

Limitations

• Default browser detection only supports: macOS detects Chrome, Edge, and Safari; Windows detects Chrome and Edge via the registry or common installation paths; Linux detects Chrome and Chromium via system commands.
• If the system cannot find the default browser, it will fall back to the Chromium bundled with Puppeteer.
• When using default browser mode, you must also set useDefaultBrowser: true and visibleBrowser: true.
• Headless mode (visibleBrowser: false) is faster and better suited for automated workflows that do not require user interaction.
• If there is a problem connecting to the browser debugging port, check whether another instance is occupying that port.
• If authentication does not work, try using the clear-auth-cookies tool to clear cookies.
• The server logs useful error information to the console, which can be used to troubleshoot issues.