screenshotmcp

Zero-dependency synchronous Python SDK for ScreenshotMCP.

pip install screenshotmcp

Hosted mode is the default

import os
from screenshotmcp import SiteScreenshotClient

client = SiteScreenshotClient(access_token=os.environ["SCREENSHOTMCP_TOKEN"])
result = client.capture("https://example.com", device="both")
print(result["files"])

Omitting base_url targets https://snapforge.web-tasarimci.com and reports mode=hosted. Hosted use requires a free-account API key or account-bound OAuth token and shares the 500 capture credits/month pool with REST, CLI, JavaScript and MCP.

Requests carry credential-free client metadata with package name, package version and hosted/self-hosted mode. A hosted failure is surfaced as SiteScreenshotError; the SDK never falls back to localhost or another origin.

Explicit self-hosted/community mode

self_hosted = SiteScreenshotClient("http://localhost:3010")

Any explicit non-managed HTTP(S) origin is mode=self-hosted. Origins containing credentials, paths, queries or fragments are rejected.

get_job(), download_job(), and download_job_file() map to persisted screenshot job routes. The previous agentforge_site_screenshot import remains available for compatibility.

Forward-compatible raw requests

Compatible public endpoints can be called before a typed helper ships with client.request('/api/v1/...', method='POST', json_body={...}). Authentication, timeout, idempotency and error redaction remain enforced; private/admin paths are rejected.

Migration from the previous default

If an earlier Python integration relied on implicit http://localhost:3010, pass base_url="http://localhost:3010" explicitly (or the first positional base URL). Omitting base_url now intentionally selects managed SnapForge.

Hosted auth onboarding metadata

The Python library never opens a browser. Use hosted_account_urls() for safe account/login/signup/upgrade URLs. SiteScreenshotError exposes code, account_url, login_url, signup_url, and upgrade_url when returned by the hosted API. Configured bearer tokens and URL secrets are redacted from error messages and bodies.

from screenshotmcp import hosted_account_urls
print(hosted_account_urls()["signupUrl"])