Give MCP hosts DOMShot tools.

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.

Install

Install the npm package where your agent can run local commands. Global install is the simplest setup because tools like Codex and Claude Code can start domshot from anywhere. Playwright Chromium is still needed for normal browser captures.

npm install -g @usedomshot/cli
npx playwright install chromium

Check the install with domshot --help and domshot mcp --help.

To update later, run npm install -g @usedomshot/cli@latest. You do not need to change the MCP config unless you intentionally pinned a package version.

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",
      "args": ["mcp"]
    }
  }
}

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

Use DOMShot with Codex, Claude Code, and other agents

DOMShot works with agents through MCP. Once connected, the agent can inspect a page, find the right card, modal, chart, or section, and save clean PNG files locally.

claude mcp add --transport stdio domshot -- domshot mcp

[mcp_servers.domshot]
command = "domshot"
args = ["mcp"]

{
  "mcpServers": {
    "domshot": {
      "command": "domshot",
      "args": ["mcp"]
    }
  }
}

What to ask your agent

Ask for the result you want in normal language. The agent decides when to inspect first, when to capture, and whether it needs a retry.

If setup does not work

Most setup issues are either the command not being on the agent's PATH, the local browser not being installed, or the agent asking for a target that is too vague.

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.

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