Overview

This repository contains the official ScreenshotOne implementation of an MCP (Model Context Protocol) server. It exposes ScreenshotOne screenshot functionality as a model-context tool that LLMs and other MCP-aware clients can call. The server lets you manage model-side context tools for generating website screenshots as part of automated workflows, chat assistants, or monitoring pipelines.

Using an MCP server for screenshots makes integrations simpler and more secure: instead of embedding screenshot logic in every client, the MCP server acts as a single trusted tool provider that returns image data and metadata. This reduces duplication, centralizes API key management, and enables real-time, low-latency screenshot workflows for downstream model-driven automation.

Features

Official MCP server implementation from ScreenshotOne, packaged as a Node.js application
Single tool: render website screenshots and return image output for model consumption
Easy integration with MCP-compatible clients (for example, Claude Desktop) via process-based servers
Simple configuration via environment variables (SCREENSHOTONE_API_KEY)
MIT-licensed and available on GitHub: https://github.com/screenshotone/mcp/

Installation / Configuration

Prerequisites: Node.js (v16+) and npm.

Clone and install

git clone https://github.com/screenshotone/mcp.git
cd mcp
npm install
npm run build

Configure your ScreenshotOne API key

Export the API key as an environment variable (example for macOS / Linux):

export SCREENSHOTONE_API_KEY="sk_XXXXXXXXXXXX"
node build/index.js

Or run inline:

SCREENSHOTONE_API_KEY=sk_XXXXXXXXXXXX node build/index.js

Integrate with an MCP-capable client (example: Claude for Desktop)

Add an MCP server entry to your Claude Desktop configuration file (~/“Library/Application Support/Claude/claude_desktop_config.json” on macOS). Example:

{
  "mcpServers": {
    "screenshotone": {
      "command": "node",
      "args": ["path/to/screenshotone/mcp/build/index.js"],
      "env": {
        "SCREENSHOTONE_API_KEY": "<your api key>"
      }
    }
  }
}

Notes:

Always keep your API key secret and rotate it if it leaks.
Run the server under a process manager (pm2, systemd, Docker) for production deployments.
If deploying in containers, inject SCREENSHOTONE_API_KEY via your container runtime or secret manager.

Available Tools / Resources

The server exposes one primary tool:

Tool name	Input (typical)	Output	Notes
render-website-screenshot	url (string), width, height, fullPage (bool), format (png/jpg), delay (ms)	Image binary (PNG/JPEG) + metadata (size, url)	Renders a screenshot of the given URL and returns image data suitable for model consumption or downstream storage.

Resource links:

GitHub: https://github.com/screenshotone/mcp/
ScreenshotOne: https://screenshotone.com
MCP spec: https://modelcontextprotocol.io/

Example usage pattern from an MCP-capable LLM:

LLM issues a tool call with the URL and rendering options.
MCP server uses the ScreenshotOne API to generate the screenshot.
Server returns image bytes (often base64-encoded) and metadata for the LLM or client to display or store.

Use Cases

Chat assistants: Let a conversational model fetch a live screenshot of a page on user request (e.g., “Show me the homepage of example.com”).
Visual QA / regression: Automate periodic captures of pages to compare against baselines and detect visual regressions.
Thumbnail generation: Produce thumbnails for link previews, catalogs, or CMS workflows.
Monitoring and alerting: Capture pages on a schedule and detect layout changes, content drift, or downtime visually.
Documentation and demos: Dynamically embed fresh screenshots into generated docs, emails, or reports.

Concrete example (developer workflow):

Add the ScreenshotOne MCP server to your assistant configuration.
User asks the assistant: “Take a screenshot of https://example.com, full page.”
Assistant issues the MCP tool call to render-website-screenshot with fullPage=true.
MCP server calls ScreenshotOne, returns the image (base64 or binary), and the assistant displays or stores the image.

Troubleshooting & Best Practices

If builds fail, run npm ci or delete node_modules and reinstall.
Ensure SCREENSHOTONE_API_KEY is valid and has sufficient quota.
For high-throughput usage, run the MCP server behind a supervisor (pm2 or systemd) and scale horizontally.
Log incoming tool calls and API responses, but never log API keys or sensitive image data.
Consider caching frequent captures to reduce API usage and latency.

License

This project is open-source under the MIT License. See the repository for license details and contribution guidelines: https://github.com/screenshotone/mcp/README.md

ScreenshotOne Official MCP Server Implementation