ScreenshotAPI

ScreenshotAPI MCP 服务

ScreenshotAPI 的官方 MCP 服务。它为你的 AI 助手提供 8 个工具，可用于网页截图、将 URL 和 HTML 转换为 PDF、录制滚动视频、感知 JavaScript 的网页抓取（Markdown、文本、HTML）以及批量截取。你只需用日常语言提出请求，服务就会调用 API。助手还会收到截图作为图像，因此可以查看它截取的页面。

兼容 Claude Desktop、Claude Code、Cursor、Windsurf、VS Code、Cline、Codex 以及任何其他兼容 MCP 的客户端。

项目	值
软件包	@screenshotapinet/mcp
传输方式	stdio
Node.js	>=18

快速开始

1. 注册 ScreenshotAPI，并从控制面板复制你的 API 密钥。

2. Cursor 用户可以一键安装：

   

3. 其他用户：将以下内容添加到 MCP 客户端配置中（确切的文件路径请参阅按客户端安装）：

{
  "mcpServers": {
    "screenshotapi": {
      "command": "npx",
      "args": ["-y", "@screenshotapinet/mcp"],
      "env": {
        "SCREENSHOTAPI_TOKEN": "<YOUR_API_KEY>"
      }
    }
  }
}

4. 重启客户端。

5. 测试：询问 “截取 https://example.com 的屏幕截图”

目录

• 快速开始
• 按客户端安装
• 验证是否正常工作
• 工具参考
• 提示词示例
• 错误代码
• 工作原理
• 环境变量
• 从源代码构建
• 故障排除
• 链接
• 许可证

按客户端安装

要求

• Node.js 18 或更高版本
• 终端中可使用 npx
• ScreenshotAPI API 密钥（注册）

Claude Desktop

添加到 claude_desktop_config.json（设置 → 开发者 → 编辑配置）：

{
  "mcpServers": {
    "screenshotapi": {
      "command": "npx",
      "args": ["-y", "@screenshotapinet/mcp"],
      "env": {
        "SCREENSHOTAPI_TOKEN": "<YOUR_API_KEY>"
      }
    }
  }
}

保存后重启 Claude Desktop。

Claude Code

claude mcp add screenshotapi --env SCREENSHOTAPI_TOKEN=<YOUR_API_KEY> -- npx -y @screenshotapinet/mcp

添加服务后，启动新的 Claude Code 会话。

Cursor

一键安装：

或者手动添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "screenshotapi": {
      "command": "npx",
      "args": ["-y", "@screenshotapinet/mcp"],
      "env": {
        "SCREENSHOTAPI_TOKEN": "<YOUR_API_KEY>"
      }
    }
  }
}

保存后重启 Cursor。

Windsurf

添加到 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "screenshotapi": {
      "command": "npx",
      "args": ["-y", "@screenshotapinet/mcp"],
      "env": {
        "SCREENSHOTAPI_TOKEN": "<YOUR_API_KEY>"
      }
    }
  }
}

保存后重启 Windsurf。

VS Code / GitHub Copilot

添加到 VS Code 的 settings.json：

{
  "mcp": {
    "servers": {
      "screenshotapi": {
        "command": "npx",
        "args": ["-y", "@screenshotapinet/mcp"],
        "env": {
          "SCREENSHOTAPI_TOKEN": "<YOUR_API_KEY>"
        }
      }
    }
  }
}

保存后重启 VS Code。

Cline

打开 MCP Servers 面板 → 配置 → 高级 MCP 设置。将以下内容添加到 cline_mcp_settings.json：

{
  "mcpServers": {
    "screenshotapi": {
      "command": "npx",
      "args": ["-y", "@screenshotapinet/mcp"],
      "env": {
        "SCREENSHOTAPI_TOKEN": "<YOUR_API_KEY>"
      }
    }
  }
}

保存后重启 Cline。

Codex CLI

codex mcp add screenshotapi --env SCREENSHOTAPI_TOKEN=<YOUR_API_KEY> -- npx -y @screenshotapinet/mcp
codex mcp list

添加服务后，启动新的 Codex 会话。

任何其他 MCP 客户端

使用此配置：

{
  "command": "npx",
  "args": ["-y", "@screenshotapinet/mcp"],
  "env": {
    "SCREENSHOTAPI_TOKEN": "<YOUR_API_KEY>"
  }
}

验证运行情况

设置完成后，试试以下操作：

提示词	预期工具
截取 https://example.com 的屏幕截图	take_screenshot
在 iPhone 尺寸的屏幕上以深色模式截取 stripe.com 的屏幕截图	使用 width、dark_mode 的 take_screenshot
截取 https://news.ycombinator.com 的完整页面，并屏蔽广告	使用 full_page、block 的 take_screenshot
将 https://example.com/invoice 保存为 A4 PDF，文件路径为 ./invoice.pdf	使用 format、save_path 的 generate_pdf
阅读 https://react.dev/learn 并总结内容	scrape_page
为 https://apple.com 制作 10 秒的滚动 GIF	record_scrolling_video
截取这 5 个竞争对手首页的屏幕截图	bulk_screenshots
批量任务 1f2e... 完成了吗？	get_bulk_status

工具参考

全部 8 个工具都封装了 ScreenshotAPI REST API。渲染工具（take_screenshot、generate_pdf、scrape_page、record_scrolling_video）会调用 GET https://shot.screenshotapi.net/v3/screenshot，并使用 output=json，且共用以下页面准备选项。每个工具都接受 url 或 custom_html。

共用渲染选项

分组	参数
视口	width（默认值 1680，最大值 7680）、height（默认值 876，最大值 4320）
时序	delay、wait_for_event（load / domcontentloaded / networkidle）、lazy_load、scroll_delay、timeout
页面操作	css、css_url、js、js_url、remove_selector、blur_selector、selector_to_click、click_recursion、scroll_to_element、adjust_top
屏蔽	block（列表：ads、tracking、cookie_banners、chat_widgets、javascript、stylesheets、images、media、fonts、text_tracks、xhr、fetch、event_source、websockets、manifest）、block_specific_requests
模拟	dark_mode、grayscale（0-100）、enable_incognito、user_agent、accept_languages、headers、cookies、template_id、proxy、latitude、longitude、timezone
缓存	fresh、enable_caching、ttl（仅限屏幕截图和 PDF）
存储	result_file_name、byob、storage_service、bucket_name（仅限屏幕截图和 PDF）

take_screenshot

将页面捕获为图像并返回托管图像 URL。图像也会以内嵌形式返回，以便助手查看。整页截图是例外，因为通常太高而无法查看；传入 include_image=true 即可将其以内嵌形式返回。

参数	必填	说明
url	二选一	要捕获的 URL
custom_html	二选一	要渲染的原始 HTML，不使用 URL
file_type	否	png（默认）、jpg、webp
full_page	否	捕获整个可滚动页面。默认值为 false
retina	否	2 倍像素密度。默认值为 false
image_quality	否	JPEG 质量，范围为 0-100。默认值为 80
omit_background	否	为纯背景页面设置透明背景（仅限 PNG）
thumbnail_width	否	将输出调整为此宽度，同时保持宽高比
selector	否	按 CSS 选择器捕获单个元素
clip	否	捕获一个矩形区域：{ x, y, width, height }
sizes	否	在一个请求中按多个视口尺寸捕获：[{ width, height }, ...]
include_image	否	以内嵌形式返回图像。默认值为 true；设置 full_page 时默认值为 false
save_path	否	同时将文件保存到本地

以及所有共享渲染选项。

generate_pdf

将 URL 或原始 HTML 转换为 PDF，并返回托管 PDF URL。如果未指定 format（且未指定 width/height），则整个页面会转换为一个连续的 PDF 页面。

参数	必填	说明
url	二选一	要转换的 URL
custom_html	二选一	要转换的原始 HTML
format	否	A0–A6、Letter、Legal、Tabloid、Ledger
landscape	否	横向。默认值为 false
page_range	否	仅保留这些页面，例如 1-3
print_background	否	包含背景颜色和图像
media	否	print 或 screen CSS
save_path	否	同时将 PDF 保存到本地

以及所有共享渲染选项。

scrape_page

在真实浏览器中渲染页面，因此会先运行 JavaScript，然后提取页面内容。服务会下载提取出的文件，并以内嵌方式返回其内容。相同请求中还会截取屏幕截图。

参数	必填	描述
url	二选一	要抓取的 URL
custom_html	二选一	要处理的原始 HTML
extract	否	可选值：markdown、text、html、image_urls。默认值为 markdown
include_content	否	是否以内嵌方式返回提取出的内容。默认值为 true
max_content_chars	否	每个提取文件的截断字符数。默认值为 50000

另外还支持视口、计时、页面操作、拦截和模拟选项。

record_scrolling_video

录制浏览器向下滚动页面的过程，并返回托管视频的 URL。

参数	必填	描述
url	二选一	要录制的 URL
custom_html	二选一	要录制的原始 HTML
file_type	否	mp4（默认值）、webm、gif
scroll_speed	否	slow、normal（默认值）、fast
duration	否	秒数，范围为 0-60
scroll_back	否	结束时滚回顶部
start_immediately	否	在页面加载完成前开始录制
video	否	录制视口画面，时长为 duration 秒，不进行滚动
sizes	否	在多种视口尺寸下录制：[{ width, height }, ...]，最多 10 种
save_path	否	同时在本地保存视频（仅支持单一尺寸）

另外还支持视口、计时、页面操作、拦截和模拟选项。

bulk_screenshots

POST https://api.screenshotapi.net/v1/bulk/json 可将最多 50 个 URL 作为一个任务提交。仅限付费套餐使用。

参数	必填	描述
screenshots	是	[{ url, ...options }]。选项使用原始 API 名称（file_type、width、full_page、block_ads 等）
defaults	否	应用于每个条目的选项，除非条目自行覆盖

bulk_screenshots_csv

POST https://api.screenshotapi.net/v1/bulk/csv 会上传一个包含 url 列的 CSV。其他列均为对应行的渲染选项。仅限付费套餐使用。

参数	必填	描述
csv_path	二选一	本地 CSV 文件的路径
csv_content	二选一	CSV 文本

get_bulk_status

GET https://api.screenshotapi.net/v1/bulk/csv/status 会返回任务的 percent_complete、successful_urls 和 failed_urls。

参数	必填	描述
uuid	是	任务 uuid

download_bulk_results

GET https://api.screenshotapi.net/v1/bulk/csv/download 每个 URL 返回一行，包含 url、status、screenshot 和 error_message。

Parameter	Required	Description
uuid	Yes	作业 uuid

提示词示例

截图

• 为 https://linear.app 截图
• 在 390px 宽的移动端视口和深色模式下，为 https://github.com 截图。
• 截取 https://vercel.com/pricing 的完整页面，并屏蔽广告和 Cookie 横幅。
• 仅截取 https://example.com/pricing 上的定价表格（选择器 #pricing）。
• 为我们的预发布网站截图，并模糊所有带有 .user-email 类的内容。
• 告诉我从德国访问时，https://www.bbc.com 的德语页面是什么样的。

PDF

• 将 https://example.com/report 转换为 A4 横向 PDF，并保存到 ./report.pdf。
• 将这份 HTML 发票转换为 Letter 尺寸的 PDF。
• 将 https://docs.example.com/guide 中的第 2-4 页导出为 PDF。

抓取

• 阅读 https://react.dev/learn 并告诉我要点。
• 获取 https://example.com 运行 JavaScript 后渲染的 HTML。
• 列出 https://unsplash.com 上的所有图片 URL。

视频

• 录制 https://stripe.com 的慢速滚动 MP4，并在最后滚回顶部。
• 以桌面端和移动端尺寸为我们的着陆页制作滚动 GIF。

批量

• 为这 20 个 URL 截图，尺寸为 1440x900，并隐藏 Cookie 横幅。
• 我的批量作业状态如何？完成后下载结果。

错误代码

工具调用不会导致服务崩溃。上游错误会以结构化工具结果的形式返回，其中包含 error、code、message 和 guidance 字段，以便客户端解释问题并建议解决方法。

Code	Meaning
310	目标 URL 重定向次数过多
400	参数无效（URL、文件类型、代理、地理位置、CSS/JS URL、裁剪区域、模板）或目标 SSL 问题
401	缺少或无效的 SCREENSHOTAPI_TOKEN，或订阅未激活
402	因欠费或用量超过套餐配额两倍而暂停服务
403	截图配额已用尽、试用期已结束，或目标拒绝连接
404	账户未订阅套餐或未开通试用
407	代理隧道连接失败
408	页面渲染耗时过长
429	每分钟请求次数过多
444	目标网站关闭了连接或未返回任何内容
495	目标网站的 SSL/TLS 版本或加密套件不匹配
499	此服务停止等待 API 响应（参见 SCREENSHOTAPI_REQUEST_TIMEOUT_MS）
500	ScreenshotAPI 内部错误，可安全重试
502	服务无法连接到 ScreenshotAPI
503	ScreenshotAPI 或目标页面暂时不可用

缺少 URL 时的错误结果示例：

{
  "error": "url_required",
  "code": 400,
  "message": "Provide either 'url' or 'custom_html'.",
  "guidance": "Pass a fully qualified URL including the protocol, e.g. 'https://example.com', or pass custom_html instead."
}

完整列表请参阅 ScreenshotAPI 错误文档。

工作原理

这是一个封装 ScreenshotAPI REST API 的 stdio MCP 服务。

运行时：

1. MCP 客户端通过 npx 启动服务进程。
2. 客户端读取工具列表。
3. 当提示词匹配某个工具时，客户端会调用该工具。
4. 服务会验证输入，使用 output=json 调用 ScreenshotAPI，并返回包含托管文件 URL 的结构化 JSON。
5. 对于截图，服务还会下载图像并以内联方式返回。对于抓取任务，服务会下载提取出的 Markdown、文本或 HTML，并返回其内容。

每次调用时都会从环境中读取 API 密钥，并将其作为 token 参数发送。服务会在响应到达模型之前，从每个响应中移除令牌。对于值非常长的请求（例如大型 custom_html），会使用包含 JSON 正文的 POST 请求，以避免 URL 长度限制。

环境变量

变量	必填	默认值	描述
SCREENSHOTAPI_TOKEN	是		你的 ScreenshotAPI API 密钥
SCREENSHOTAPI_REQUEST_TIMEOUT_MS	否	180000	上游请求超时时间（毫秒）
SCREENSHOTAPI_MAX_INLINE_IMAGE_BYTES	否	3500000	内联返回给模型的最大截图大小

从源代码构建

git clone https://github.com/Screenshot-API/screenshot-mcp.git
cd screenshot-mcp
npm install
npm run build

直接运行：

SCREENSHOTAPI_TOKEN=<YOUR_KEY> node dist/cli.js

使用 MCP Inspector 检查：

SCREENSHOTAPI_TOKEN=<YOUR_KEY> npx @modelcontextprotocol/inspector node dist/cli.js

故障排除

更新后客户端仍使用旧工具列表： 重启客户端，并确认其加载了最新的 npm 版本。

401 token_required： SCREENSHOTAPI_TOKEN 未在 MCP 客户端配置的 env 块中设置。

401 invalid_token： 密钥错误，或已在控制面板中轮换。请从控制面板复制当前密钥。

截图以 URL 返回，但没有图像： 图像大小超过 SCREENSHOTAPI_MAX_INLINE_IMAGE_BYTES，或者这是一次 full_page 截取。请使用 thumbnail_width、降低 image_quality 的 jpg，或设置 include_image=true。

页面空白或仅部分加载： 添加 delay（例如 3000），使用 wait_for_event=networkidle，或为包含延迟加载图像的页面设置 lazy_load=true。

截图中出现 Cookie 横幅或弹窗： 传入 block: ["cookie_banners", "ads", "chat_widgets"]，或使用 remove_selector 移除特定元素。

遇到 CAPTCHA 或机器人拦截： 通过住宅代理 proxy 路由请求。请参阅代理文档。

超时： 页面加载缓慢时，可能需要提高 timeout（API 端，默认 100000 ms）和 SCREENSHOTAPI_REQUEST_TIMEOUT_MS（此服务，默认 180000 ms）。某些 MCP 客户端也有自己的工具调用超时时间。

链接

• ScreenshotAPI 网站
• API 文档
• 查询构建器
• 定价
• GitHub 仓库

许可证

MIT