Webpage Screenshot MCP

Capture screenshots of web URLs or local .html files using Playwright Chromium. Each capture is saved to disk and exposed as a Resource with URI scheme screenshots://{screenshotId}, that compatible MCP clients can read.

Usage & Requirements

Requirements

• Node.js v20+
• pnpm v10.x

Configure MCP in your IDE

Claude Code

claude mcp add webpageScreenshot pnpm dlx @srigi/mcp-webpage-screenshot

JSON configuration

Add the following configuration to your MCP settings:

{
  "mcpServers": {
    "webpageScreenshot": {
      "command": "pnpm",
      "args": ["dlx", "@srigi/mcp-webpage-screenshot"],
      "autoApprove": [
        "create_webpage_file_screenshot",
        "create_webpage_url_screenshot"
      ]
    }
  }
}

Usage examples

Prompts you can try:

Screenshot of an URL

• Take a screenshot of https://example.com and save it as example-website.png.
• Make another screenshot with viewport width 640 and height 1280px.

Screenshot of a local file

• Capture a full-page screenshot of example/page.html and save it alongside.

Logging

You can configure logging by adding flags to the args array in your MCP configuration:

"webpageScreenshot": {
  "command": "pnpm",
  "args": [
    "dlx", "@srigi/mcp-webpage-screenshot",
    "--debug", "/absolute/path/to/debug.log",
    "--pretty-print"
  ]
}

Debug flags:

• No --debug: logging disabled
• --debug: writes to debug.log in the current working directory of the running MCP
• --debug /absolute/path/to/debug.log: writes logs to that absolute path (absolute paths only)
• --pretty-print: pretty formatted JSON logs

🛠️ Tools & Resources

Tool: create_webpage_file_screenshot

Create a screenshot of a local HTML file:

• loads the local HTML via file://
• waits for networkidle
• captures PNG (Buffer), supports full-page height
• saves the image to a workspace-relative path
• adds an in-memory Resource entry and returns a screenshots:// URI

Parameters:

• screenshotFilePath: File where to save the screenshot (relative to the current workspace)
• webpageFilePath: HTML file path of the webpage to screenshot (relative to the current workspace)
• workspacePath: The current workspace absolute path
• viewport (optional):
  • width: number (default 1280)
  • height: number | "fullpage" (default 768). Use "fullpage" to capture the entire page height.

Security constraints: all paths are resolved relative to workspacePath

Tool: create_webpage_url_screenshot

Create a screenshot of a web URL:

• validates HTTP/HTTPS URLs only (rejects file://, data://, etc.)
• implements retry logic with progressive timeouts (5s, 9s, 15s)
• waits for networkidle and dynamic content loading
• applies security headers (DNT, User-Agent) and safe browser settings
• captures PNG (Buffer), supports full-page height
• saves the image to a workspace-relative path
• adds an in-memory Resource entry and returns a screenshots:// URI

Parameters:

• screenshotFilePath: File where to save the screenshot (relative to the current workspace)
• url: URL of the webpage to screenshot (HTTP/HTTPS only)
• workspacePath: The current workspace absolute path
• viewport (optional):
  • width: number (default 1280)
  • height: number | "fullpage" (default 768). Use "fullpage" to capture the entire page height.

Security features: protocol validation, security headers, download blocking, CSP respect, HTTPS error handling

Resource: screenshots://{screenshotId}

Each created screenshot is added to an in-memory registry and exposed as a Resource with:

• uri: screenshots://<screenshotId>
• blob: data:image/png;base64,...
• mimeType: image/png
• text: original webpage file path or URL used for the screenshot

Note:

• Listing resources is not implemented (list is not available).

Development

Requirements

• Node.js v20+
• PNPM v10

The install step will post-install Playwright Chromium, but it's not guaranteed to work. To ensure the shell browser is installed, run:

pnpm playwright install --with-deps --only-shell chromium

Steps

1. Install dependencies:

   pnpm install

2. Start the TypeScript compiler in watch mode:

   pnpm dev

3. (Optional) Start the MCP Inspector:

   pnpm dev:inspector

4. Update your MCP configuration for development (adjust the path to the compiled JS):

   {
     "mcpServers": {
       "webpageScreenshot": {
         "command": "node",
         "args": ["/absolute/path/to/compiled/src/index.js", "--debug", "--pretty-print"],
         "autoApprove": [
            "create_webpage_file_screenshot", "create_webpage_url_screenshot"
          ]
       }
     }
   }

Testing

Run tests:

pnpm test

Tests use Vitest with global logger setup in vitest.setup.ts to handle TypeScript/JavaScript module isolation.

Notes:

• Restart the MCP in your IDE after source changes to pick up newly compiled code.