mcp-server-screenshot 0.1.0

Pixel-perfect website screenshot service exposed as both REST API and MCP server

Screenshot API

Pixel-perfect website screenshot service that captures any URL as PNG, JPEG, or PDF. Exposed as both a REST API (FastAPI) and an MCP server for use with Claude Desktop, Cursor, and other MCP-compatible clients. Uses Playwright with a pooled Chromium browser for fast, reliable rendering.

Quick Start

Docker (recommended)

docker-compose up -d

The API will be available at http://localhost:8500.

Local Development

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
bash setup_browsers.sh
python server.py

MCP Installation

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "screenshot": {
      "command": "python",
      "args": ["/path/to/mcp-services/screenshot-api/mcp_server.py"]
    }
  }
}

Cursor

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "screenshot": {
      "command": "python",
      "args": ["/path/to/mcp-services/screenshot-api/mcp_server.py"]
    }
  }
}

Via uvx (after PyPI publish)

{
  "mcpServers": {
    "screenshot": {
      "command": "uvx",
      "args": ["mcp-server-screenshot"]
    }
  }
}

API Documentation

Endpoints

POST /screenshot

Take a screenshot with full control over parameters.

Request body (JSON):

Parameter	Type	Default	Description
url	string	required	URL to capture
viewport_width	int	1280	Viewport width (320-3840)
viewport_height	int	720	Viewport height (240-2160)
full_page	bool	false	Capture entire scrollable page
format	string	"png"	Output: "png", "jpeg", or "pdf"
wait_for	string	null	CSS selector to wait for
block_cookies	bool	false	Block cookie consent banners
inject_css	string	null	Custom CSS to inject
delay_ms	int	0	Extra delay after load (0-10000)

Example:

curl -X POST http://localhost:8500/screenshot \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "full_page": true, "format": "png"}' \
  -o screenshot.png

GET /screenshot

Simple GET-based screenshot (no CSS injection support).

curl "http://localhost:8500/screenshot?url=https://example.com&width=1920&height=1080&format=jpeg" -o screenshot.jpg

Query parameters: url, width, height, full_page, format, wait_for, block_cookies, delay_ms

POST /screenshot/base64

Same parameters as POST /screenshot, returns JSON with base64-encoded image.

curl -X POST http://localhost:8500/screenshot/base64 \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

Response:

{
  "url": "https://example.com",
  "format": "png",
  "content_type": "image/png",
  "base64": "iVBORw0KGgo...",
  "size_bytes": 45231
}

GET /health

Health check. Returns {"status": "ok"}.

GET /stats

Cache and usage statistics.

POST /admin/keys

Create API keys (requires X-Admin-Key header matching ADMIN_KEY env var).

curl -X POST "http://localhost:8500/admin/keys?key=my-api-key&tier=pro&owner=alice" \
  -H "X-Admin-Key: your-admin-key"

Authentication

Header	Description
X-API-Key	Your API key. Omit for free tier.

Response Headers

Header	Description
X-Cache-Key	Truncated cache key for debugging
X-Rate-Remaining	Remaining requests today

MCP Tools

When used as an MCP server, two tools are available:

take_screenshot

Returns the screenshot as a viewable image (ImageContent for PNG/JPEG, TextContent with base64 for PDF).

screenshot_to_base64

Returns the screenshot as a base64 string in a TextContent response, suitable for passing to other tools or embedding.

Both tools accept: url, viewport_width, viewport_height, full_page, format, wait_for, inject_css.

Pricing Tiers

Tier	Daily Limit	Auth
Free	100/day per IP	No key needed
Basic	1,000/day	API key
Pro	10,000/day	API key
Enterprise	100,000/day	API key

Caching

Screenshots are cached using SHA256(url + params) as the key. Default TTL is 1 hour (configurable via CACHE_TTL). Expired entries are cleaned up automatically every 30 minutes.

Self-Hosting

Environment Variables

See .env.example for all options. Key settings:

• CACHE_DIR - Where cached screenshots are stored (default: /data/cache)
• CACHE_TTL - Cache duration in seconds (default: 3600)
• MAX_FREE_DAILY - Free tier daily limit (default: 100)
• ADMIN_KEY - Secret key for the admin endpoints
• PORT - API port (default: 8500)

Docker Resource Limits

The default docker-compose.yml limits the container to 2 CPU cores and 2GB RAM. Adjust in the deploy.resources section as needed.

Persistent Storage

The docker-compose file uses a named volume screenshot-data for the cache and SQLite database. To use a host directory instead:

volumes:
  - /path/on/host:/data