Webpage Screenshot MCP Server

1# Webpage Screenshot MCP Server
2 
3An MCP (Model Context Protocol) server that captures screenshots of web pages using Puppeteer. This server allows AI agents to visually verify web applications and see their progress when generating web apps.
4 
5![Screen Recording May 27 2025 (2)](https://github.com/user-attachments/assets/9f186ec4-5a5c-449b-9a30-a5ec0cdba695)
6 
7 
8## Features
9 
10- **Full page screenshots**: Capture entire web pages or just the viewport
11- **Element screenshots**: Target specific elements using CSS selectors
12- **Multiple formats**: Support for PNG, JPEG, and WebP formats
13- **Customizable options**: Set viewport size, image quality, wait conditions, and delays
14- **Base64 encoding**: Returns screenshots as base64 encoded images for easy integration
15- **Authentication support**: Manual login and cookie persistence
16- **Default browser integration**: Use your system's default browser for a more natural experience
17- **Session persistence**: Keep browser sessions open for multi-step workflows
18 
19## Installation
20 
21### Quick Start (Claude Desktop Extension)
22 
23Drag and drop the generated `screenshot-webpage-mcp.dxt` file into Claude Desktop for automatic installation!
24 
25### Manual Installation
26 
27To install and build the MCP from source:
28 
29```bash
30# Clone the repository (if you haven't already)
31git clone https://github.com/ananddtyagi/webpage-screenshot-mcp.git
32cd webpage-screenshot-mcp
33 
34# Install dependencies
35npm install
36 
37# Build the project
38npm run build
39```
40 
41The MCP server is built using TypeScript and compiled to JavaScript. The `dist` folder contains the compiled JavaScript files. 
42 
43### Adding to Claude or Cursor
44 
45To add this MCP to Claude Desktop or Cursor:
46 
471. **Claude Desktop**:
48   - Go to Settings > Developer
49   - Click "Edit Config"
50   - Add the following:
51 
52   ```json
53    "webpage-screenshot": {
54      "command": "node",
55      "args": [
56        "~/path/to/webpage-screenshot-mcp/dist/index.js"
57      ]
58    }
59   ```
60   - Save and reload Claude
61 
622. **Cursor**:
63   - Open Cursor and go to Cursor Settings > MCP
64   - Click "Add new global MCP server"
65   - Add the following:
66  
67  ```json
68    "webpage-screenshot": {
69      "command": "node",
70      "args": ["~/path/to/webpage-screenshot-mcp/dist/index.js"]
71    }
72   ```
73 
74   - Save and reload Cursor
75 
76## Usage
77 
78### Tools
79 
80This MCP server provides several tools:
81 
82#### 1. login-and-wait
83 
84Opens a webpage in a visible browser window for manual login, waits for user to complete login, then saves cookies.
85 
86```json
87{
88  "url": "https://example.com/login",
89  "waitMinutes": 5,
90  "successIndicator": ".dashboard-welcome",
91  "useDefaultBrowser": true
92}
93```
94 
95- `url` (required): The URL of the login page
96- `waitMinutes` (optional): Maximum minutes to wait for login (default: 5)
97- `successIndicator` (optional): CSS selector or URL pattern that indicates successful login
98- `useDefaultBrowser` (optional): Whether to use the system's default browser (default: true)
99 
100#### 2. screenshot-page
101 
102Captures a screenshot of a given URL and returns it as base64 encoded image.
103 
104```json
105{
106  "url": "https://example.com/dashboard",
107  "fullPage": true,
108  "width": 1920,
109  "height": 1080,
110  "format": "png",
111  "quality": 80,
112  "waitFor": "networkidle2",
113  "delay": 500,
114  "useSavedAuth": true,
115  "reuseAuthPage": true,
116  "useDefaultBrowser": true,
117  "visibleBrowser": true
118}
119```
120 
121- `url` (required): The URL of the webpage to screenshot
122- `fullPage` (optional): Whether to capture the full page or just the viewport (default: true)
123- `width` (optional): Viewport width in pixels (default: 1920)
124- `height` (optional): Viewport height in pixels (default: 1080)
125- `format` (optional): Image format - "png", "jpeg", or "webp" (default: "png")
126- `quality` (optional): Quality of the image (0-100), only applicable for jpeg and webp
127- `waitFor` (optional): When to consider page loaded - "load", "domcontentloaded", "networkidle0", or "networkidle2" (default: "networkidle2")
128- `delay` (optional): Additional delay in milliseconds after page load (default: 0)
129- `useSavedAuth` (optional): Whether to use saved cookies from previous login (default: true)
130- `reuseAuthPage` (optional): Whether to use the existing authenticated page (default: false)
131- `useDefaultBrowser` (optional): Whether to use the system's default browser (default: false)
132- `visibleBrowser` (optional): Whether to show the browser window (default: false)
133 
134#### 3. screenshot-element
135 
136Captures a screenshot of a specific element on a webpage using a CSS selector.
137 
138```json
139{
140  "url": "https://example.com/dashboard",
141  "selector": ".user-profile",
142  "waitForSelector": true,
143  "format": "png",
144  "quality": 80,
145  "padding": 10,
146  "useSavedAuth": true,
147  "useDefaultBrowser": true,
148  "visibleBrowser": true
149}
150```
151 
152- `url` (required): The URL of the webpage
153- `selector` (required): CSS selector for the element to screenshot
154- `waitForSelector` (optional): Whether to wait for the selector to appear (default: true)
155- `format` (optional): Image format - "png", "jpeg", or "webp" (default: "png")
156- `quality` (optional): Quality of the image (0-100), only applicable for jpeg and webp
157- `padding` (optional): Padding around the element in pixels (default: 0)
158- `useSavedAuth` (optional): Whether to use saved cookies from previous login (default: true)
159- `useDefaultBrowser` (optional): Whether to use the system's default browser (default: false)
160- `visibleBrowser` (optional): Whether to show the browser window (default: false)
161 
162#### 4. clear-auth-cookies
163 
164Clears saved authentication cookies for a specific domain or all domains.
165 
166```json
167{
168  "url": "https://example.com"
169}
170```
171 
172- `url` (optional): URL of the domain to clear cookies for. If not provided, clears all cookies.
173 
174## Default Browser Mode
175 
176The default browser mode allows you to use your system's regular browser (Chrome, Edge, etc.) instead of Puppeteer's bundled Chromium. This is useful for:
177 
1781. Using your existing browser sessions and extensions
1792. Manually logging in to websites with your saved credentials
1803. Having a more natural browsing experience for multi-step workflows
1814. Testing with the same browser environment as your users
182 
183To enable default browser mode, set `useDefaultBrowser: true` and `visibleBrowser: true` in your tool parameters.
184 
185### How Default Browser Mode Works
186 
187When you enable default browser mode:
188 
1891. The tool will attempt to locate your system's default browser (Chrome, Edge, etc.)
1902. It launches your browser with remote debugging enabled on a random port
1913. Puppeteer connects to this browser instance instead of launching its own
1924. Your existing profiles, extensions, and cookies are available during the session
1935. The browser window remains visible so you can interact with it manually
194 
195This mode is particularly useful for workflows that require authentication or complex user interactions.
196 
197## Browser Persistence
198 
199The MCP server can maintain a persistent browser session across multiple tool calls:
200 
2011. When you use `login-and-wait`, the browser session is kept open
2022. Subsequent calls to `screenshot-page` or `screenshot-element` with `reuseAuthPage: true` will use the same page
2033. This allows for multi-step workflows without having to re-authenticate
204 
205## Cookie Management
206 
207Cookies are automatically saved for each domain you visit:
208 
2091. After using `login-and-wait`, cookies are saved to the `.mcp-screenshot-cookies` directory in your home folder
2102. These cookies are automatically loaded when visiting the same domain again with `useSavedAuth: true`
2113. You can clear cookies using the `clear-auth-cookies` tool
212 
213## Example Workflow: Protected Page Screenshots
214 
215Here's an example workflow for taking screenshots of pages that require authentication:
216 
2171. **Manual Login Phase**
218 
219```json
220{
221  "name": "login-and-wait",
222  "parameters": {
223    "url": "https://example.com/login",
224    "waitMinutes": 3,
225    "successIndicator": ".dashboard-welcome",
226    "useDefaultBrowser": true
227  }
228}
229```
230 
231This will open your default browser with the login page. You can manually log in, and once complete (either by detecting the success indicator or after navigating away from the login page), the session cookies will be saved.
232 
2332. **Take Screenshots Using Saved Session**
234 
235```json
236{
237  "name": "screenshot-page",
238  "parameters": {
239    "url": "https://example.com/account",
240    "fullPage": true,
241    "useSavedAuth": true,
242    "reuseAuthPage": true,
243    "useDefaultBrowser": true,
244    "visibleBrowser": true
245  }
246}
247```
248 
249This will take a screenshot of the account page using your saved authentication cookies in the same browser window.
250 
2513. **Take Screenshots of Specific Elements**
252 
253```json
254{
255  "name": "screenshot-element",
256  "parameters": {
257    "url": "https://example.com/dashboard",
258    "selector": ".user-profile-section",
259    "useSavedAuth": true,
260    "useDefaultBrowser": true,
261    "visibleBrowser": true
262  }
263}
264```
265 
2664. **Clear Cookies When Done**
267 
268```json
269{
270  "name": "clear-auth-cookies",
271  "parameters": {
272    "url": "https://example.com"
273  }
274}
275```
276 
277This workflow allows you to interact with protected pages as if you were a regular user, completing the full authentication flow in your default browser.
278 
279## Headless vs. Visible Mode
280 
281- **Headless mode** (`visibleBrowser: false`): Faster and more suitable for automated workflows where no user interaction is needed.
282- **Visible mode** (`visibleBrowser: true`): Shows the browser window, allowing for user interaction and manual verification. Required for `useDefaultBrowser: true`.
283 
284## Platform Support
285 
286The default browser detection works on:
287 
288- **macOS**: Detects Chrome, Edge, and Safari
289- **Windows**: Detects Chrome and Edge via registry or common installation paths
290- **Linux**: Detects Chrome and Chromium via system commands
291 
292## Troubleshooting
293 
294### Common Issues
295 
2961. **Default browser not found**: If the system can't find your default browser, it will fall back to Puppeteer's bundled Chromium.
2972. **Connection issues**: If there are problems connecting to the browser's debugging port, check if another instance is already using that port.
2983. **Cookie issues**: If authentication isn't working, try clearing cookies with the `clear-auth-cookies` tool.
299 
300### Debugging
301 
302The MCP server logs helpful error messages to the console when issues occur. Check these messages for troubleshooting information.
303