MCP 服务器

webpage screenshot mcp

Captures screenshots of web URLs or local HTML files using Playwright Chromium and exposes them as resources.

README

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

Install dependencies:
```
pnpm install
```
Start the TypeScript compiler in watch mode:
```
pnpm dev
```
(Optional) Start the MCP Inspector:
```
pnpm dev:inspector
```

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"
       ]
    }
  }
}