Site-Shot

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, fewer vision tokens).

A Site-Shot API key is required, and it takes a paid Site-Shot API plan: captures draw on that account's existing API allowance and limits. The key comes from your Site-Shot dashboard; pricing lists the plans. The no-signup browser tool at https://www.site-shot.com/ is for checking output quality; it does not issue keys.

Claude Code (plugin)

This repository doubles as 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, so Claude Code prompts you for it rather than asking you to paste it into this repository, a config file, or a chat message.

Install

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

or from inside a session:

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

Both forms resolve the marketplace from GitHub, so they work only after these manifests are published on the repository's public default branch — not from a local branch or a fork you have not pushed.

Try it before that

Load the plugin directory for a single session:

claude --plugin-dir /absolute/path/to/site-shot-mcp/plugins/site-shot

Two things matter here. Pass an absolute path — --plugin-dir is resolved against the session's working directory. And start that session from an ordinary project directory, not from this checkout: this repo is the site-shot-mcp package, so npm resolves the name locally, finds no linked binary, and the server dies with sh: site-shot-mcp: command not found before Claude Code ever sees it. From an unrelated directory npx fetches the published package and starts it normally — checked both ways: exit 127 in this checkout, clean stdio start from an empty one.

To exercise the real install path instead — marketplace resolution, manifests and the required setting — add the checkout itself as a marketplace:

claude plugin marketplace add /absolute/path/to/site-shot-mcp
claude plugin install site-shot@site-shot

That installs into your user scope; undo it with claude plugin uninstall site-shot@site-shot and claude plugin marketplace remove site-shot.

The API key

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

Installing without one is not an error — Claude Code records it as still owed (1 userConfig option not yet set (1 required)). Supply it through the masked prompt:

/plugin configure site-shot@site-shot

Configure it before expecting a capture: that setting is what feeds the server its key. What Claude Code does while it is unset — whether the server is launched at all, whether the tools are offered — is Claude Code's own behaviour and is not something documented here from observation.

The server's side is independent of that. When run directly over stdio without a key, it still starts and prints a warning on stderr. 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.

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.2.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). As with Claude Code, these resolve the marketplace from GitHub, so they work only once these manifests are on the public default branch; before that, point codex plugin marketplace add at a local checkout path instead.

Installing is not the same as being configured, and neither is the same as a capture succeeding. Installation only puts the manifests in place. The server still needs the key below, and a capture still needs a Site-Shot plan with allowance left on it.

The API key

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

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

env_vars is an allow-list of names, not values: no key appears in this descriptor, in the command below, or in the manual config.toml entry further down. You provision the key in the environment of the session you start Codex from.

macOS defaults to zsh, where read -p starts a coprocess rather than printing a prompt — and a bash-labelled code fence does not change the shell you paste into. 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.

What this does not do is configure a Codex you start some other way. A desktop launcher or a remote session begins from its own environment, so it will run the server without a key until you provision one there too.

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.2.0"]
env_vars = ["SITESHOT_API_KEY"]

codex mcp add site-shot -- npx -y site-shot-mcp@1.2.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.

Either route, the caveat from the Claude Code section applies: unless the entry sets cwd, Codex starts the server from wherever you ran Codex, so running it inside this repo hits the same local-name collision.

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):

{
  "mcpServers": {
    "site-shot": {
      "command": "npx",
      "args": ["-y", "site-shot-mcp"],
      "env": { "SITESHOT_API_KEY": "YOUR_API_KEY" }
    }
  }
}

3. 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.

Every integration above runs the same local stdio server, and that package is published on npm and in the official MCP Registry. It is not listed in the shared ChatGPT/Codex public plugin directory or in Claude's remote connector directory: both of those routes take a hosted HTTPS MCP endpoint, which Site-Shot has not deployed. Doing so is a separate decision.

Tools

Two tools, both returning the screenshot as an MCP image. 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

Returns the screenshot as an MCP image.

"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. Versions up to 1.1.0 printed pixel sizes for width / height that the API does not use — an agent that omitted them to take "the default" got a different viewport, with nothing in the returned image to reveal it. 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 →

capture_full_page

Same as capture_screenshot with full-page capture enabled.

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).

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

Local development

npm install
npm run check            # syntax check
npm run smoke            # offline tests (stubbed fetch, no API key needed)
node test/integration.mjs  # real stdio handshake against the local source
npm run test:plugin      # plugin/marketplace metadata tests
npm run validate:plugin  # claude plugin validate --strict (needs the claude CLI)
SITESHOT_API_KEY=yourkey npm start   # run the server on stdio

Requirements

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

License

MIT