---
title: "MCP Tools Reference"
description: "Reference for the HTML to Image MCP tools: generate-image-from-html and screenshot-url, their parameters, output and credit cost."
url: "https://html2img.com/docs/mcp/tools/"
---

# MCP Tools Reference

The MCP server exposes two tools. Both render in real Chrome, both cost 1 credit per successful image, and both return a full-resolution CDN URL plus a downscaled preview image so the model can review the result.

The parameters mirror the [REST API parameters](https://html2img.com/docs/parameters/), with three differences: there is no `webhook_url` (MCP calls are synchronous), there is no `scale_to_fit`, and the default viewport is 1920x1080 rather than the REST API's 1440x900.

## generate-image-from-html

Renders HTML and CSS to a PNG or PDF. Best for content the model designs itself: social cards, OG images, invoices, certificates, receipts, charts and more.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `html` | string | Yes | Complete, self-contained HTML to render. Put CSS in an inline `<style>` block. |
| `css` | string | No | Extra CSS injected into the page. |
| `width` | integer | No | Viewport width in pixels (1-5000). Defaults to 1920. |
| `height` | integer | No | Viewport height in pixels (1-5000). Defaults to 1080. |
| `fullpage` | boolean | No | Capture the full scrollable height instead of the viewport. |
| `dpi` | integer | No | Device pixel ratio (1-4) for higher-resolution output. |
| `ms_delay` | integer | No | Milliseconds to wait before capture, 1-5000 (e.g. to let fonts or animation settle). |
| `wait_for_selector` | string | No | Wait until this CSS selector appears before capturing. |
| `format` | string | No | `png` (default) or `pdf`. With `pdf`, `width`, `height`, `dpi` and `fullpage` are ignored. See the [format parameter](https://html2img.com/docs/parameters/format/). |

## screenshot-url

Captures a screenshot of a live, publicly accessible web page.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | Yes | The fully-qualified URL to capture (`https://...`). |
| `css` | string | No | CSS injected into the page before capture (e.g. to hide cookie banners). |
| `width` | integer | No | Viewport width in pixels (1-5000). Defaults to 1920. |
| `height` | integer | No | Viewport height in pixels (1-5000). Defaults to 1080. |
| `fullpage` | boolean | No | Capture the full scrollable height instead of the viewport. |
| `selector` | string | No | Capture only the element matching this CSS selector (first match wins). Maximum 255 characters. |
| `dpi` | integer | No | Device pixel ratio (1-4). |
| `ms_delay` | integer | No | Milliseconds to wait before capture, 1-5000. |
| `wait_for_selector` | string | No | Wait until this CSS selector appears before capturing. |
| `format` | string | No | `png` (default) or `pdf`. With `pdf`, `width`, `height`, `dpi`, `fullpage` and `selector` are ignored. See the [format parameter](https://html2img.com/docs/parameters/format/). |

## Output

On success, a tool returns two things to the model:

1. **A text part** with the full-resolution image URL on the `i.html2img.com` CDN and your remaining credit balance.
2. **An image part** - a downscaled preview of the render, so the model can see what it produced and iterate. PDFs return the URL only, plus a line noting the file is an A4 vector PDF with selectable text; there is no inline preview for PDFs.

The full-resolution file always lives at the returned URL. The inline preview is intentionally small so it fits inside the message-size limits of MCP clients.

> **Note**
>
> The image URL is permanent for the lifetime of a paid account, so the model can hand it straight back to you, drop it into a document, or post it onward.

## Credits and errors

- Each successful image costs **1 credit**, exactly like the REST API.
- If you are out of credits, the tool returns a clear message instead of an image, and no credit is spent. Top up on the [pricing page](https://html2img.com/pricing/).
- Render failures (timeouts, unreachable pages, invalid input) come back as readable tool errors so the assistant can adjust and try again.

## Images in your HTML

> **Note**
>
> Remote images load fine when the URL is publicly accessible, and base64 data URIs (`data:image/png;base64,...`) work when the asset is not hosted anywhere. For AI-generated pages, data URIs are the more reliable choice - a model cannot invent a remote URL that actually exists. Self-contained HTML with an inline `<style>` block renders most reliably.

## See also

- [Install and setup](https://html2img.com/docs/mcp/installation/) for your AI client.
- [Parameters reference](https://html2img.com/docs/parameters/) for the shared rendering options in depth.