Set up HCTI in Gemini CLI

Capture a webpage or turn HTML/CSS into a PNG, WebP, or PDF with HTML/CSS to Image.

You’ll need: an HCTI account with image credits. Sign in through your browser when connecting—no API key to copy.

This guide uses Gemini CLI, Google’s terminal-based agent. Install and sign in to Gemini CLI before connecting HCTI.

Add HCTI for the current project from your terminal:

gemini mcp add --transport http hcti https://mcp.hcti.io

1. Start gemini and run /mcp auth hcti.
2. Sign in to HCTI and review the organization and permissions. Include usage:read to check your account usage.
3. Run /mcp list to check the connection.

Ask “Use HCTI to check my image usage and account limits” to verify access without rendering an image.

{
  "mcpServers": {
    "hcti": {
      "httpUrl": "https://mcp.hcti.io"
    }
  }
}

Send this prompt after connecting:

Use HTML/CSS to Image to screenshot https://example.com as a PNG.
Set viewport_width to 1440 and device_scale to 1. Return the image URL.

Open the returned image URL to view your screenshot. Replace https://example.com with your own public URL.

Try a small card with explicit text, colors, and dimensions:

Use HCTI to render this HTML and CSS as a PNG at device_scale 1.
HTML: <div class="card">Hello from HCTI</div>
CSS: .card { width: 1200px; height: 630px; display: flex;
align-items: center; justify-content: center; background: #172554;
color: white; font: 64px sans-serif; }
Return the hosted image URL.

The result is a dark blue card with centered white text. Edit the text or CSS and render again to refine it.

Give Gemini the relevant stylesheet and page title, then ask:

Read the brand colors and typography in this workspace. Create
self-contained HTML/CSS for a 1200×630 Open Graph card titled
"New release". Render it with HCTI at device_scale 1 and return the PNG URL.

Open the result to check the title, spacing, and brand colors. Ask Gemini to update the HTML/CSS and render again for changes. HCTI needs the rendered markup and accessible assets, so source component files may need to be converted first.

Available tools

These core tools work across MCP clients. Access depends on the permissions approved for your connection. Ask your assistant to use HCTI by name.

Account usage

Screenshots and rendering

Template management

See rendering parameters and the Template Editor for image options and reusable designs. The complete tools reference also covers proxies, storage destinations, Open Graph configurations, and required permissions.

For a permission-denied error, reconnect and approve the required access before retrying. Usage checks and maximum batch-size checks require usage:read.

Run /mcp list inside Gemini CLI or gemini mcp list from your terminal to inspect connection errors. Run /mcp auth hcti to sign in again if needed.

Check that the server uses httpUrl in settings and that HCTI is enabled. If you configured includeTools or excludeTools, make sure they allow the tool you want to use. Approve tool calls when Gemini prompts you.

HCTI fetches webpages from its hosted service. Use a publicly accessible URL; it cannot reach your computer’s localhost. For HTML/CSS rendering, supply the file contents and accessible assets rather than local file paths. Check your HCTI dashboard for available image credits.

See shared MCP troubleshooting for authentication and rendering errors, or choose another client.