site-shot-mcp
OfficialCapture public web page screenshots and return them to an AI agent as image content.
Take viewport screenshots of any public URL with
capture_screenshot.Capture the entire scrollable page with
capture_full_pageorfull_page: true.Set viewport size (
width,height) and cap captured height (max_height).Choose PNG or JPEG output.
Render through a country proxy with optional language, time-zone, and geolocation overrides.
Wait before capture for SPAs/animations (
wait_ms, up to 30s).Remove ads and cookie banners by default.
Return screenshots as MCP image content, with no saved library, listing, markdown conversion, or scheduling.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@site-shot-mcp Capture a full-page screenshot of https://news.ycombinator.com"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
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.
Add the server to your agent — pick your client below: Claude Code · Codex CLI · Claude Desktop, Cursor and other clients.
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-shotThen, in a Claude Code session, enter the key:
/plugin configure site-shot@site-shotFrom 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-shotRestart 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-shotExercised 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-shotThe 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-mcpGemini 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
Get a Site-Shot API key at https://www.site-shot.com/start/.
Add this to your Claude Desktop config (
claude_desktop_config.json), with your key in place ofYOUR_API_KEY:
{
"mcpServers": {
"site-shot": {
"command": "npx",
"args": ["-y", "site-shot-mcp"],
"env": { "SITESHOT_API_KEY": "YOUR_API_KEY" }
}
}
}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 |
| string (required) | — | Page to capture |
| boolean |
| Capture the whole scrollable page |
| number | API default | Viewport / device size |
|
|
| Image format. |
| boolean |
| Remove ads |
| boolean |
| Remove cookie-consent popups |
| string | — | Proxy country as a two-letter ISO 3166-1 alpha-2 code, e.g. |
| boolean |
| Error out if the country has no proxy, instead of falling back to the US |
| string | — | Manual overrides |
| number | API default | Extra wait before capture (SPAs/animations) |
| number | 20000 (full page) | Cap captured height |
| number | 2000 | Largest side of any returned image, 256 to 2000 px. Set |
| number | — | Return at most this many tiles of a tall PNG |
| number | 0 | Start the tiles at this row, to continue after |
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,heightandwait_msare 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 — passfalseto 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 |
| yes | Your Site-Shot API key (used as |
| no | Default for |
| 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 toolscapture_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
Scored across 2 tools
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.
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.
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.
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
Related MCP Connectors
Let your AI agent see any public web page: one screenshot tool, returns the page as an image.
Screenshot API for AI agents. Any public page as image or PDF, banners hidden, 227 countries.
Screenshot any public web page from an AI agent. Free without signup, or with an API key.
Screenshot, PDF and Open Graph image API for AI agents: capture pages, render PDFs, make OG images.
Related MCP Servers
- AlicenseBqualityCmaintenanceAn official MCP server implementation that allows AI assistants to capture website screenshots through the ScreenshotOne API, enabling visual context from web pages during conversations.138MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to capture screenshots of web pages using automated browser sessions. Supports full-page and element-specific screenshots, device simulation, and JavaScript execution for comprehensive web testing and monitoring.6MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to capture screenshots of any public URL, returning images inline with page metadata. Supports full-page captures, custom wait times, and timeouts.131 npmMIT
- AlicenseAqualityDmaintenanceEnables AI agents to capture clean web screenshots and extract main article content from any web page, with automatic removal of cookie banners, ads, and boilerplate.2MIT