MCP server

Give MCP hosts DOMShot tools.

Run domshot-mcp over stdio so an MCP-compatible host can inspect pages, choose candidates, create contact sheets, and capture polished PNGs.

What MCP means here

MCP lets an agent host discover and call tools provided by another program. In DOMShot, the MCP server exposes screenshot tools to the agent. The agent can ask DOMShot to inspect a page, plan useful shots, capture one element, or create a complete shot pack without manually running shell commands.

Use MCP when the agent host supports tools and should decide when DOMShot is useful during a larger task, such as writing a feature section with screenshots.

Install

Install the npm package in the environment where the MCP host can run local commands. Playwright Chromium is still needed for normal browser captures. If npm cannot find the package yet, the public package release is still pending approval.

npm install @domshot/agent
npx playwright install chromium

Expected result: the domshot-mcp binary can be launched by the MCP host.

Client config

Add DOMShot as an MCP server in your host's config. The exact config file location depends on the host, but the command is the same.

{
  "mcpServers": {
    "domshot": {
      "command": "domshot-mcp"
    }
  }
}

Expected result: the host lists DOMShot tools such as capture_domshot and create_domshot_shot_pack.

Tools

The tools are grouped by how much decision-making they do. Start with inspection or planning when the page is unfamiliar. Use capture tools when the target is already clear.

Tool	Use
`capture_domshot`	Capture one selected element by selector or target.
`inspect_domshot_page`	Inspect visible candidates for an intent or target.
`recommend_domshot_shots`	Recommend useful candidates and styles.
`create_domshot_plan`	Plan shots before writing PNG files.
`capture_domshot_plan`	Capture screenshots from a saved plan.
`create_domshot_contact_sheet`	Write a labeled contact sheet for visual review.
`capture_domshot_set`	Capture several similar elements.
`create_domshot_shot_pack`	Create polished PNGs, a contact sheet, and a report.

Example shot pack input

Use this when an agent is creating a homepage, blog, docs, or feature section and needs several useful images. DOMShot will inspect the page, choose candidates, style them, and write assets to the output folder.

{
  "url": "https://example.com",
  "intent": "homepage feature section",
  "target": "feature cards",
  "count": 4,
  "outputDir": "artifacts/homepage",
  "style": "auto"
}

Expected output: JSON text with file paths, selected items, warnings, a contact sheet path, and a report path. The image payloads are written to disk, not returned inline.

Example current-page CDP input

Use this for logged-in or private pages where the user has already opened Chrome and reached the right tab. DOMShot attaches through Chrome's debugging port and captures from the current browser session.

{
  "intent": "dashboard feature visuals",
  "target": "dashboard cards",
  "count": 4,
  "outputDir": "artifacts/dashboard",
  "style": "auto",
  "browser": {
    "mode": "cdp",
    "endpointURL": "http://127.0.0.1:9222"
  }
}

Keep outputs from private pages in local ignored folders and do not paste private URLs, selectors, screenshots, cookies, or auth state into public docs or issues.

Result shape

MCP tools return JSON text with paths, dimensions, selectors, warnings, decisions, confidence, contact sheet paths, report paths, and fallback status. V1 writes files to disk and does not return base64 image payloads.

{
  "path": "/absolute/path/artifacts/card.png",
  "width": 1200,
  "height": 1200,
  "selector": "[data-card='pricing']",
  "fallback": false,
  "bytes": 12345
}

fallback: false means the main DOM render path worked. fallback: true means DOMShot used visible pixels because the DOM render path was blocked or unsupported.

Agent guidance

Use DOMShot as the eyes and camera. Let the agent decide the story, review confidence and warnings, compare contact sheets, and retry with a narrower target, kinds, steps, or selector when needed.

Use inspect_domshot_page when the agent is not sure what elements exist.

Use create_domshot_plan when the agent should decide before writing images.

Use create_domshot_shot_pack when the agent needs final assets for a content section.