Screenshot Api

面向 AI Agent 的截图 API

让你的 AI Agent 拥有视觉能力。一次 MCP 工具调用即可返回一张 Agent 真正能看到的截图。

→ 加入早期体验候补名单 · 含免费套餐 · 托管 API 即将推出

---

功能介绍

AI Agent 无法查看网页——它们拿到的是原始 HTML，内容杂乱、不完整（缺少 JavaScript 渲染的内容），而且充斥着模板代码。这个 MCP 服务为 Claude、Cursor 和任何兼容 MCP 的 Agent 提供三个原生工具：

工具	返回内容
take_screenshot	URL → Agent 可直接查看的 base64 PNG/JPEG
describe_page	一次调用返回截图 + 标题 + H1 + 元描述
capture_pdf	URL → A4 PDF

describe_page 是其关键优势：大多数 Agent 既需要截图，也需要一些文本上下文。这个工具省去了一次往返调用。

---

架构

flowchart LR
  Agent[MCP agent] -->|tool call| MCP[screenshot-api MCP]
  MCP --> Cache{URL cache<br/>5-min TTL}
  Cache -->|hit| Resp[base64 PNG / PDF]
  Cache -->|miss| PW[Playwright + stealth]
  PW --> Page[Rendered page]
  Page --> Resp
  MCP -->|HTTP| API[Fastify capture API]
  API --> PW

MCP 工具契约： take_screenshot(url, format?)、describe_page(url)、capture_pdf(url)——为 Agent 循环设计的结构化输出，而不是原始 HTTP 包装器。

故障模式：

• 被机器人拦截／遇到 CAPTCHA → 使用隐身规避；遇到严格拦截时仍可能失败 → 返回明确错误（不要臆造空白页面）
• Playwright 崩溃／超时 → 有限重试，之后以状态信息安全失败
• 同一 URL 的缓存请求风暴 → TTL 缓存合并重复的 Agent 循环请求
• 托管与自托管 → 自托管可让数据保留在本地；托管服务以运维控制权换取正常运行时间

---

快速开始（自托管，免费）

Claude Desktop

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "screenshot-api": {
      "command": "npx",
      "args": ["-y", "screenshot-api-mcp"]
    }
  }
}

重启 Claude Desktop。然后询问：

“截取 https://news.ycombinator.com 的截图，并总结排名前 5 的故事”

Cursor

设置 → MCP → 添加服务：

{
  "name": "screenshot-api",
  "command": "npx",
  "args": ["-y", "screenshot-api-mcp"]
}

Python（LangChain / CrewAI）

from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient({
    "screenshot": {
        "command": "npx",
        "args": ["-y", "screenshot-api-mcp"],
        "transport": "stdio",
    }
})

tools = await client.get_tools()
# → [take_screenshot, describe_page, capture_pdf]

---

为什么不直接使用 HTML？

• JavaScript 渲染的内容 — 单页应用、延迟加载的内容区块和 canvas 元素对爬虫不可见。Playwright 会渲染所有内容。
• 隐身模式 — 约 40% 的真实 URL 会向简单爬虫返回机器人拦截页面。内置规避机制。
• 响应缓存 — 循环中两次访问同一 URL？第二次调用会立即返回（5 分钟 TTL，不会重复计费）。
• 原生支持 MCP — 结构化输出专为 Agent 循环设计，而非后加的 HTTP 包装器。

---

托管 API（即将推出）

自托管版本需要 Node.js 和本地安装的 Playwright/Chromium（约 300MB）。托管 API 无需这些——Agent 请求一个端点，即可获取图像。

加入候补名单 — 早期体验用户可享 3 个月 6 折优惠。

计划中的套餐：

套餐	价格	每月截图数
免费试用	$0	100（7 天）
入门版	$19/mo	2,000
专业版	$49/mo	10,000

---

HTTP API（自托管）

GET /screenshot

参数	类型	默认值	说明
url	string	必填	公共 URL（仅限 http/https）
format	png | jpeg | pdf	png	输出格式
full_page	true | false	false	完整可滚动页面
width	number	1280	视口宽度（320–3840）
height	number	800	视口高度（200–2160）

curl "http://localhost:3099/screenshot?url=https://example.com" -o out.png

GET /health

{ "status": "ok", "browserConnected": true }

---

本地开发

npm install
npm run dev        # tsx watch
npm test           # vitest + real Chromium (~60s)
npm run typecheck

---

部署到 Fly.io（大规模自托管）

export PATH="$HOME/.fly/bin:$PATH"
flyctl auth login
flyctl launch --no-deploy --copy-config
flyctl secrets set PROXY_SECRET=$(openssl rand -hex 24)
flyctl deploy
flyctl checks list   # /health should be green

内存： Fly 默认的 256MB 会导致 Chromium 因内存不足而崩溃。fly.toml 已预设为 1GB。不要将内存缩减到 512MB 以下。

在 GitHub 仓库密钥中添加 FLY_API_TOKEN，即可在推送到 main 时启用自动部署。

---

配置

所有设置均通过环境变量配置。请参阅 .env.example。

主要变量：PORT（3099）、MAX_CONCURRENCY（2）、PROXY_SECRET（为空 = 本地关闭身份验证）、NAV_TIMEOUT_MS（20000）。

---

路线图

阶段 A——验证 (当前)

• 含 3 个工具的 MCP 服务
• 隐身模式／绕过 Cloudflare
• 响应缓存（5 分钟 TTL）
• 着陆页 + 候补名单
• 发布到 npm（screenshot-api-mcp）
• 在 Smithery + mcp.so + Glama 上架
• 20 位候补名单注册用户 ← 进入阶段 B 的门槛

阶段 B — 托管 API （如果通过关卡）

• Lemon Squeezy 计费（使用量套餐）
• API 密钥签发 + 用量计量
• 部署到 Fly.io（1GB VM，min_machines_running=1）
• 首位付费客户

阶段 C — 增长

• SEO 内容（“如何让 Claude 处理截图”）
• Zapier 集成
• LangChain / CrewAI 工具包