Skip to main content
Glama

Site-Shot MCP server

Give Claude, Cursor, and other AI agents the ability to see public web pages — take website screenshots with Site-Shot over the Model Context Protocol.

Real Chromium rendering · full-page capture · country proxies · automatic ad & cookie-banner removal (cleaner images for the model to read).

Quick start

  1. Get an API key at https://www.site-shot.com/start/. A confirmed account's key comes with the free plan: 100 API captures a month, no card needed.

  2. Add the server to your agent — pick your client below: Claude Code · Codex CLI · Claude Desktop, Cursor and other clients.

  3. Ask: "Take a screenshot of example.com." The agent calls the server and shows you the image.

About the key

The free plan renews every month; once its 100 captures are spent, the API answers 403 until it renews. Free-plan captures come from the default location or the US; other countries need a paid plan, and a request for one is refused but still counts toward the month. Paid plans start at $5/mo for 2,000 captures (pricing). Accounts confirmed before 2026-10-30 switch the free plan on with one button on https://www.site-shot.com/start/; an account that has had a paid plan before does not get it. Captures draw on that account's API allowance and limits. The no-signup browser tool at https://www.site-shot.com/ is for checking output quality; it does not issue keys.

Related MCP server: MCP Browser Screenshot Server

Claude Code (plugin)

This repository is a Claude Code plugin marketplace. The plugin runs the published site-shot-mcp package over stdio and declares the API key as a required sensitive setting, which Claude Code collects in a masked prompt rather than asking you to paste it into a config file or a chat message.

Install

claude plugin marketplace add site-shot/site-shot-mcp
claude plugin install site-shot@site-shot

Then, in a Claude Code session, enter the key:

/plugin configure site-shot@site-shot

From inside a session the first two steps are /plugin marketplace add site-shot/site-shot-mcp and /plugin install site-shot@site-shot.

The API key

The plugin declares SITESHOT_API_KEY as a required, sensitive setting. /plugin configure asks for it, masks it as you type, and Claude Code substitutes it into the server's environment as ${user_config.SITESHOT_API_KEY}. Storage of the value is Claude Code's to handle.

Installing from the command line does not ask for the key: the install prints 1 userConfig option not yet set (1 required) and names /plugin configure. Configure it before expecting a capture. Until the key is set, Claude Code does not list the server (claude mcp list shows no site-shot entry) and the capture tools do not appear (observed with Claude Code 2.1.283). Run /plugin configure site-shot@site-shot again to replace a wrong key.

The server's own behaviour is separate. When run directly over stdio without a key, it still starts and prints a warning on stderr, and the capture tools return a clear missing-key error instead of an image.

The plugin adds one skill (site-shot:website-screenshots) and the two capture tools below. It declares no hooks, no monitors and no scheduled capture jobs; the only process it launches is the declared stdio MCP server.

Updating

The plugin pins an exact site-shot-mcp release (now site-shot-mcp@1.3.0), so a new server version reaches you through a plugin update:

claude plugin marketplace update site-shot
claude plugin update site-shot@site-shot

Restart Claude Code afterwards.

Codex CLI (plugin)

This repository is also a Codex plugin marketplace. It installs the same plugin directory as Claude Code does — one shared skill, the same pinned site-shot-mcp@1.3.0 over stdio — with its own manifest, because the two hosts wire the credential differently.

Install

codex plugin marketplace add site-shot/site-shot-mcp
codex plugin add site-shot@site-shot

Exercised against Codex CLI 0.147.0 on macOS (arm64). Installing is not the same as being configured, and neither is the same as a capture succeeding: the server still needs the key below, and a capture still needs allowance left on that key's account, from the free plan or a paid plan.

The API key

Codex forwards the variable named in the plugin's descriptor:

{ "command": "npx", "args": ["-y", "site-shot-mcp@1.3.0"], "env_vars": ["SITESHOT_API_KEY"] }

env_vars is an allow-list of names, not values: no key appears in this descriptor, in the commands below, or in the manual config.toml entry further down. You provision the key in the environment Codex starts from, in one of two ways.

For one session (most private). macOS defaults to zsh, where read -p starts a coprocess rather than printing a prompt, so invoke bash explicitly:

bash -c 'read -r -s -p "Site-Shot API key: " SITESHOT_API_KEY && printf "\n" && export SITESHOT_API_KEY && exec codex'

-s keeps the key off the screen, nothing here puts it in argv, and the export is scoped to that child session instead of lingering in the shell you typed from. You type the key at each launch.

For every session. Keep the key in a file only you can read, and export it from your shell profile (~/.zshrc or ~/.bashrc):

mkdir -p ~/.config/site-shot && chmod 700 ~/.config/site-shot
# put the key in ~/.config/site-shot/api-key with your editor, then:
chmod 600 ~/.config/site-shot/api-key
# in ~/.zshrc or ~/.bashrc
export SITESHOT_API_KEY="$(cat ~/.config/site-shot/api-key)"

The trade-off: every program started from those shells can read the variable. A Codex started from a desktop launcher or a remote session does not read your shell profile, so it runs the server without a key; start Codex from a terminal instead. If the key ever arrives as the literal text ${SITESHOT_API_KEY}, the server says so: that is an env table Codex did not expand, and env_vars is the fix.

Updating

codex plugin marketplace upgrade site-shot
codex plugin add site-shot@site-shot

The first command refreshes the marketplace from GitHub; the second installs the plugin version it now lists (the plugin pins an exact site-shot-mcp release).

Manual MCP setup instead

If you would rather not install the plugin, the same stdio server can be configured by hand. This is an alternative to the plugin, not an addition — run both and you have two configurations of one server. Pick one.

[mcp_servers.site-shot]
command = "npx"
args = ["-y", "site-shot-mcp@1.3.0"]
env_vars = ["SITESHOT_API_KEY"]

codex mcp add site-shot -- npx -y site-shot-mcp@1.3.0 writes that entry for you; add env_vars afterwards, since codex mcp add --env KEY=VALUE would store the key in the file in clear text. Check it with codex mcp get site-shot. If you already have an entry like this and now install the plugin, remove the manual one deliberately with codex mcp remove site-shot — nothing here edits your configuration for you.

Gemini CLI (extension)

gemini extensions install https://github.com/site-shot/site-shot-mcp

Gemini CLI asks for your Site-Shot API key during the install (get one at https://www.site-shot.com/start/) and stores it as a sensitive setting; change it later with gemini extensions config site-shot. The extension runs npx -y site-shot-mcp@1.3.0, and gemini extensions update site-shot moves it to the next release. gemini mcp list shows the server as Connected once it starts.

Claude Desktop & other MCP clients

  1. Get a Site-Shot API key at https://www.site-shot.com/start/.

  2. Add this to your Claude Desktop config (claude_desktop_config.json), with your key in place of YOUR_API_KEY:

{
  "mcpServers": {
    "site-shot": {
      "command": "npx",
      "args": ["-y", "site-shot-mcp"],
      "env": { "SITESHOT_API_KEY": "YOUR_API_KEY" }
    }
  }
}
  1. Restart Claude Desktop. Ask it to "take a full-page screenshot of https://news.ycombinator.com" and it will call the server and show you the image.

Works the same way in any MCP client (Cursor, Cline, VS Code, LangChain, CrewAI) — point the client at npx -y site-shot-mcp with SITESHOT_API_KEY in the environment.

Already running the server in one of those clients? npx skills add site-shot/site-shot-mcp adds the website-screenshots skill, which tells the agent when to reach for the two tools and how to read their errors. The skill needs the server: on its own it can only tell the agent that setup is incomplete.

Every integration above runs the same local stdio server, published on npm and in the official MCP Registry. Hosted HTTPS MCP is a separate deployment and client-compatibility path, not something these plugin install commands configure. Publication here does not imply listing in the shared ChatGPT/Codex public plugin directory or Claude's remote connector directory.

Tools

Two tools, both returning the screenshot as MCP image content, sometimes with text items around it (see below). There is no saved library, no listing, no markdown conversion and no scheduling — this server captures images and hands them back.

capture_screenshot

Screenshot a web page (viewport by default).

Param

Type

Default

Notes

url

string (required)

—

Page to capture

full_page

boolean

false

Capture the whole scrollable page

width / height

number

API default

Viewport / device size

format

"png" | "jpeg" | "webp"

png

Image format. webp is lossless, about 35% smaller than png on the median page, max 16,383 px per side

block_ads

boolean

true

Remove ads

block_cookie_banners

boolean

true

Remove cookie-consent popups

country

string

—

Proxy country as a two-letter ISO 3166-1 alpha-2 code, e.g. "DE" (auto IP/lang/tz/geo)

strict_country

boolean

true

Error out if the country has no proxy, instead of falling back to the US

language / time_zone / geolocation

string

—

Manual overrides

wait_ms

number

API default

Extra wait before capture (SPAs/animations)

max_height

number

20000 (full page)

Cap captured height

max_image_side

number

2000

Largest side of any returned image, 256 to 2000 px. Set 1024 for a client that scales tool images down to 1024 px

max_images

number

—

Return at most this many tiles of a tall PNG

from_row

number

0

Start the tiles at this row, to continue after max_images (a new capture)

Returns the screenshot as an MCP image. A capture over 2000 px on a side comes back with a text note first: a PNG taller than 2000 px is the note followed by a text label and an image for each tile, top to bottom; any other image that large is the note followed by the whole image. Code that reads content[0] as the image should take the items with type: "image", in order, instead.

"API default" is not a number this package gets to state. width, height and wait_ms are forwarded only when you pass them, so whatever applies when you don't is decided by the Site-Shot API and can change without a release here. Pass explicit values whenever the size matters.

Country codes are ISO codes, never names. Pass "DE", not "Germany". The API matches codes exactly and would otherwise render through a US proxy without telling you, so the server rejects full names before spending a render. strict_country (on by default) likewise turns an unavailable country into an error instead of a silent US screenshot — pass false to opt back into the fallback. Supported countries →

An argument the tools do not take is refused before any capture, with the name to use: the Site-Shot API's own names such as delay_time, full_size or no_ads map to wait_ms, full_page and block_ads here.

Every failure the API answers names its HTTP status. A 401 or a 429 also says what to do next (a 401 points to where the key is set), and so does a 403, 404 or 5xx when the API sent no text of its own. When the API answers with an error card instead of a screenshot, the card is attached as an image. It shows what Site-Shot reported, which is not always the cause: for a host that does not resolve it can read "504 Gateway Timeout", so check the URL's spelling before retrying. Every retry is another capture that counts toward the month.

capture_full_page

Same as capture_screenshot with full-page capture enabled.

A PNG taller than 2000 px comes back as several image tiles, top to bottom, each at most 2000 px tall, with a short text label per tile. AI clients scale large images down before the model sees them (Claude refuses anything over 8000 px on a side), so one 10,000 px image would arrive with its text unreadable. The tiles are cut from the one capture, so they need no extra capture. Each tile is a full-resolution image the model reads, so a tall page uses far more context than one scaled-down image: about 2,700 tokens for a 1024 x 2000 tile. Tiles stop at about 18,000 tokens in all (six tiles, the top 11,760 rows, at 1024 px wide), under the 25,000 Claude Code takes from one tool call; a page wider than 6,750 px gets one tile, which can be more. The note names any rows left out at the bottom. A tall jpeg or webp comes back whole, with a note.

Some clients show less than 2000 px: Grok Bot in Cursor scales every tool image down so its long side is at most 1024 px, which halves the text in a 1024 x 2000 tile. Pass max_image_side: 1024 (or set SITESHOT_MAX_IMAGE_SIDE=1024 for every call) and tiles are at most 1024 px tall. Tiles keep the full width, so capture at a width of 1024 or less. A client that shows only a few images per reply can take them in pages: max_images: 4 returns the first four tiles and the note names the from_row to continue from. Each such call is a new capture that counts toward the month, and the page may have changed in between.

Why call this server instead of the agent's own browser?

If your agent drives a browser, it can screenshot pages itself — and for pages that must be signed into or stepped through a flow, that is the right tool. For public URLs, delegating the capture to this server is usually better engineering: every capture runs the same pipeline (no re-planning between runs), can be taken from a specific country with matching locale and time zone (country + strict_country), is scored by an image classifier with an escalating retry ladder behind it before being returned, and costs a fraction of a cent instead of a browser session plus vision tokens per look. The full comparison, both directions honestly argued: AI agent vs. screenshot API — who should capture the page.

Configuration

Env var

Required

Description

SITESHOT_API_KEY

yes

Your Site-Shot API key (used as userkey).

SITESHOT_MAX_IMAGE_SIDE

no

Default for max_image_side, 256 to 2000. For a client that cannot be told to pass the argument.

SITESHOT_SAVE_DIR

no

A directory to write each full-size image into, untouched. The result then names the file's path, so an agent on the same machine can open it whatever the client did to the inline images. Off when unset: the server writes no files.

The server is a thin wrapper over the existing Site-Shot HTTP API (https://api.site-shot.com/) — no separate backend.

Development

Running the tests, trying the plugin from a checkout, and the release steps are in DEVELOPMENT.md.

Requirements

Node.js ≥ 18 (uses the built-in fetch).

License

MIT

Available Tools

2 tools
capture_full_pageCapture full-page website screenshotAInspect

Take a full-page (entire scrollable height) screenshot of a web page with Site-Shot and return it as an image. Convenience wrapper around capture_screenshot with full-page capture enabled.

Inputs: url (required), width, height, format, +8 more.

capture_screenshotCapture website screenshotBInspect

Take a screenshot of a web page with Site-Shot and return it as an image. Renders in a real Chromium browser. Supports viewport/device sizing, full-page capture, country proxies, and automatic ad & cookie-banner removal (cleaner image, fewer vision tokens).

Inputs: url (required), width, height, format, +9 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 2 tools

    Disambiguation2/5

    The two tools are nearly identical; capture_full_page is explicitly a wrapper for capture_screenshot with full-page enabled. An agent would likely misuse them, as the difference is only a parameter.

    Naming Consistency3/5

    Both use verb_noun pattern ('capture_screenshot', 'capture_full_page'), but 'full_page' is a qualifier while 'screenshot' is the resource; inconsistent because one tool name specifies a parameter in the name itself.

    Tool Count3/5

    Two tools is minimal but arguably sufficient for a simple screenshot service. However, the duplication suggests one tool could have been omitted, making the surface slightly too heavy for the scope.

    Completeness3/5

    The set covers basic screenshot needs with features like viewport sizing, proxies, and ad removal. However, it lacks tools for specific device emulation or batch processing, which are common in screenshot services.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers