Developer documentation

Ship screenshots.
Into every agent workflow.

REST, JavaScript, Python, CLI and MCP interfaces for PNG, JPEG, WEBP, AVIF, SVG capture and screenshot-free Detailed JSON Page Context.

01 · Install

Choose the interface your agent already speaks.

Pin published versions in production. The packages are available from npm and PyPI.

npm install -g screenshotmcp-cli@0.3.0
npm install screenshotmcp-sdk@0.3.0 screenshotmcp-mcp@0.3.0
pip install screenshotmcp==0.3.0
02 · REST API

Capture and read Page Context over HTTPS.

Use /api/v1/screenshot for the core screenshot API and /api/v1/page/context for structured page data. After sign-in, the production homepage uses /api/live-capture for the account-metered live capture: PNG, JPEG, WEBP, AVIF, SVG Basic Vector and screenshot-free Detailed JSON are all delegated to MediaHarvester through a private server-side bridge. See the OpenAPI contract and live-capture guide.

PNG · JPEG · WEBP · AVIFDesktop, mobile or both. Viewport and full-page capture are supported, then final artifacts are delivered from same-origin SnapForge URLs with the correct MIME type.
Detailed JSON · Page ContextNo screenshot is generated. One viewport returns context; Both returns desktop and mobile contexts with allowlisted structured, visual and agent-friendly fields.
SVG · Basic VectorEditable vector paths produced by MediaHarvester tracing. The free live demo always uses viewport-only Basic Vector; high-detail and full-page SVG tracing are intentionally excluded.
Free account quota100 hosted capture credits per calendar month, shared by browser Studio, REST, CLI, SDK and MCP. Usage requires an account; no card is needed.
Private bridgeThe browser never receives the MediaHarvester key or private upstream address. Production reads a dedicated service credential from a read-only file-backed secret mount.
Safe failuresInvalid URLs return 400, missing account credentials return 401, monthly quota exhaustion returns 429, and temporary upstream/capacity failures are converted to safe 503 responses without secret/internal details.

Hosted account capture

curl -sS https://snapforge.web-tasarimci.com/api/live-capture \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer $SCREENSHOTMCP_TOKEN' \
  -d '{"url":"https://example.com","device":"desktop","format":"webp","fullPage":true,"delayMs":0}'
curl -sS https://snapforge.web-tasarimci.com/api/live-capture \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer $SCREENSHOTMCP_TOKEN' \
  -d '{"url":"https://example.com","device":"both","format":"json","delayMs":0}'

Core API

curl -sS https://snapforge.web-tasarimci.com/api/v1/screenshot \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer $SCREENSHOTMCP_TOKEN' \
  -d '{"url":"https://example.com","device":"both","fullPage":true}'
curl -sS https://snapforge.web-tasarimci.com/api/v1/page/context \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer $SCREENSHOTMCP_TOKEN' \
  -d '{"url":"https://example.com"}'

Hosted SnapForge requires a free account. API-key and OAuth clients share the same monthly quota. Self-hosted AGPL deployments may configure their own authentication policy.

03 · SDKs

Keep integration code small and typed.

JavaScript / TypeScript

import { SiteScreenshotClient } from "screenshotmcp-sdk";

const client = new SiteScreenshotClient({
  baseUrl: "https://snapforge.web-tasarimci.com",
  accessToken: process.env.SCREENSHOTMCP_TOKEN,
});
const result = await client.capture({
  url: "https://example.com",
  device: "both",
  fullPage: true,
});
console.log(result);
console.log(await client.context({ url: "https://example.com" }));

Python

import os
from screenshotmcp import SiteScreenshotClient

client = SiteScreenshotClient(
    "https://snapforge.web-tasarimci.com",
    access_token=os.environ["SCREENSHOTMCP_TOKEN"],
)
print(client.capture("https://example.com", device="both", full_page=True))

The clients also expose service info, context, download and absolute URL helpers. Keep credentials on the server.

04 · CLI

Try a capture from your terminal.

screenshotmcp --help
screenshotmcp login --server https://snapforge.web-tasarimci.com
screenshotmcp https://example.com --device both \
  --server https://snapforge.web-tasarimci.com
screenshotmcp context https://example.com --json \
  --server https://snapforge.web-tasarimci.com
screenshotmcp auth status --server https://snapforge.web-tasarimci.com

The site-screenshot and snapforge binaries are aliases for the same CLI.

05 · MCP

Give Claude, ChatGPT, Codex or Qwen native tools.

Connect Streamable HTTP at https://snapforge.web-tasarimci.com/mcp. The helper provides capture_website and read_page_context (protocol 2026-07-28).

import { SiteScreenshotMcpClient } from "screenshotmcp-mcp";

const client = new SiteScreenshotMcpClient({
  baseUrl: "https://snapforge.web-tasarimci.com",
  accessToken: process.env.SCREENSHOTMCP_TOKEN,
});
console.log(await client.listTools());
console.log(await client.capture({
  url: "https://example.com",
  device: "desktop",
}));

Use the MCP Registry entry for registry-aware clients.

06 · Production checklist

Keep targets and credentials safe.

  • Use HTTPS and keep bearer tokens or URL secrets in a secret manager.
  • Validate target URLs and apply request timeouts.
  • Log job IDs and artifact URLs, never Authorization headers.
  • Keep MediaHarvester credentials and private upstream addresses server-only; prefer a read-only file-backed secret in production.
  • Keep account monthly quota enforcement separate from private service-capacity policy.
  • Pin package versions and check /api/health after deployment.

Repository source, OpenAPI, examples and the publication record are in docs/.