MCP Server
Connect AI agents to ScreenshotAPI over the Model Context Protocol. Four tools for hosted website screenshots, HTML screenshots, mobile screenshots, and URL-to-PDF.
Overview
The ScreenshotAPI MCP server lets any Model Context Protocol client — Claude, Cursor, VS Code, Codex — capture hosted screenshots and PDFs through four narrow, action-oriented tools. The tool names are intentionally specific so a model can choose the right capture path without reasoning about a generic API wrapper.
| Tool | Use when |
|---|---|
capture_webpage_screenshot | An agent needs a PNG, JPEG, or WebP screenshot from a public or authorized URL. |
capture_html_screenshot | An agent has raw HTML and needs an image without launching a local browser. |
generate_webpage_pdf | An agent needs a PDF export from a URL or HTML document. |
capture_mobile_screenshot | An agent needs a mobile-sized screenshot (390×844, 2× DPR) from a public or authorized URL. |
Each tool writes the result to a local output directory and returns a JSON payload with outputPath, contentType, bytes, screenshotId, durationMs, cache, and creditsRemaining — so the agent gets a file path and usage metadata instead of a large binary in the context window.
Status: the MCP server runs locally over stdio today. Public npm and Docker publication is pending namespace confirmation, and the hosted remote connector is on the roadmap. The MCP Registry name is to.screenshotapi/mcp-server. Until publish, use the local config below or the REST API.
Configure your client
Get an API key
Create a free account and generate a key. The server reads it from the SCREENSHOTAPI_KEY environment variable.
Add the server to your MCP config
Build the package, then point your client at the entry file:
bun install
bun --cwd packages/mcp-server run build{
"mcpServers": {
"screenshotapi": {
"command": "bun",
"args": ["/absolute/path/to/packages/mcp-server/src/index.ts"],
"env": {
"SCREENSHOTAPI_KEY": "sk_live_your_key_here"
}
}
}
}Once the package is on npm, no local build is required:
{
"mcpServers": {
"screenshotapi": {
"command": "npx",
"args": ["@screenshotapi/mcp-server"],
"env": {
"SCREENSHOTAPI_KEY": "sk_live_your_key_here"
}
}
}
}Restart your client
Restart the MCP client so it picks up the new server, then ask it to capture a URL.
Most clients (Claude Desktop, Cursor, Codex) use the mcpServers shape above. VS Code reads a servers block in .vscode/mcp.json. Check each client's MCP docs for the exact config path:
Claude Desktop & Claude Code
Add the server to your Claude MCP config, or use claude mcp add.
Cursor
Add the server to .cursor/mcp.json (project) or your global Cursor config.
VS Code
Add the server under .vscode/mcp.json and enable it in agent mode.
Environment variables
| Variable | Required | Default | Purpose |
|---|---|---|---|
SCREENSHOTAPI_KEY | Yes | — | Your API key (sk_live_...). |
SCREENSHOTAPI_BASE_URL | No | https://screenshotapi.to | Override the API base URL. |
SCREENSHOTAPI_OUTPUT_DIR | No | ./screenshotapi-captures | Directory where captured files are written. |
Tool parameters
All four tools accept the same capture options as the REST API — width, height, fullPage, type, quality, colorScheme, waitUntil, waitForSelector, delay, blockAds, removeCookieBanners, removePopups, stealthMode, devicePixelRatio, cacheTtl, preloadFonts, and more. capture_webpage_screenshot, capture_html_screenshot, and capture_mobile_screenshot take a type of png (default), jpeg, or webp; generate_webpage_pdf accepts a url or html. See the Screenshot API reference for the full list and constraints.
Safety model
The local server rejects localhost and common private-network targets before calling ScreenshotAPI. ScreenshotAPI's server-side validation enforces the same boundaries.
- API-key auth via the
SCREENSHOTAPI_KEYenvironment variable. - Private IP and
localhostblocking for untrusted agent requests. - Conservative defaults for viewport size, timeout, and cache TTL.
- File-path and metadata outputs by default instead of oversized binary payloads.
- Capture public or authorized URLs only — never paywalled, private, or unauthorized account content.
Don't use MCP yet? Use REST
Until the package is published, the production-ready path is the REST API and OpenAPI schema, which work in every agent today:
curl "https://screenshotapi.to/api/v1/screenshot?url=https://example.com&type=png&fullPage=true" \
-H "x-api-key: sk_live_your_key_here" \
--output screenshot.pngSee the AI agent integration guide for REST, OpenAPI, and framework examples.
Resources
MCP server page
Overview, tools, and install surfaces.
Server card (JSON)
Machine-readable tool schema, package names, and auth model.
Well-known server card
Discovery endpoint for MCP clients and registries.
Agent install guide
Setup instructions in agent-readable Markdown.
OpenAPI schema
REST contract for GPT Actions and tool builders.
AI agent guide
REST, OpenAPI, and framework integration.