Scrappey MCP Server

Scrappey MCP 服务

一个用于与 Scrappey.com 基于浏览器的 Web 自动化和数据提取功能交互的 Model Context Protocol（MCP）服务。可直接在 smithery.ai/server/@pim97/mcp-server-scrappey 试用。

概述

此 MCP 服务为 AI 模型与 Scrappey 的 Web 自动化平台搭建桥梁，让你能够：

• 创建和管理浏览器会话
• 通过 Scrappey 基于浏览器的基础设施发送 HTTP 请求
• 执行浏览器操作（点击、输入、滚动等）
• 渲染依赖常见机器人管理系统 JavaScript 挑战页面的网站（Cloudflare、Datadome、Kasada 等）
• 在页面需要时完成交互式挑战组件（Turnstile、reCAPTCHA、hCaptcha 等）
• 截取屏幕截图并录制视频
• 拦截网络请求

此服务适用于正当的开发用途——应用和集成测试、监控自己的服务，以及收集你获准访问的数据。请参阅负责任的使用。

设置

安装

npm install
npm run build

配置

1. 从 Scrappey.com 获取 Scrappey API 密钥
2. 设置环境变量：

SCRAPPEY_API_KEY=your_api_key_here

Claude Desktop 配置

将以下内容添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "scrappey": {
      "command": "node",
      "args": ["path/to/dist/scrappey-mcp.js"],
      "env": {
        "SCRAPPEY_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cursor IDE 配置

Cursor 可通过设置支持 MCP 服务。可通过以下任一方式进行配置：

选项 1：通过 Cursor 设置界面

1. 打开 Cursor 设置（Ctrl+, 或 Cmd+,）
2. 搜索“MCP”或“Model Context Protocol”
3. 添加新的 MCP 服务，并填写：
   • 名称：scrappey
   • 命令：node
   • 参数：["C:\\Users\\pim_d\\Desktop\\scrappey.com\\mcp-smith\\mcp-server-scrappey\\dist\\scrappey-mcp.js"]
   • 环境变量：添加 SCRAPPEY_API_KEY 并填入你的 API 密钥

选项 2：通过设置 JSON

1. 打开 Cursor 设置（Ctrl+Shift+P 或 Cmd+Shift+P）
2. 输入“Preferences: Open User Settings (JSON)”
3. 添加 MCP 服务配置：

{
  "mcp.servers": {
    "scrappey": {
      "command": "node",
      "args": ["C:\\Users\\pim_d\\Desktop\\scrappey.com\\mcp-smith\\mcp-server-scrappey\\dist\\scrappey-mcp.js"],
      "env": {
        "SCRAPPEY_API_KEY": "your_api_key_here"
      }
    }
  }
}

注意：请根据 MCP 服务的安装位置调整 dist/scrappey-mcp.js 的路径。

配置完成后，重启 Cursor 以加载 MCP 服务。你应该能在 AI 聊天界面中看到 Scrappey 工具。

可用工具

1. 创建会话（scrappey_create_session）

创建一个新的浏览器会话，该会话会保留 Cookie 和其他状态。

{
  "proxy": "http://user:pass@ip:port",
  "proxyCountry": "UnitedStates",
  "premiumProxy": true,
  "mobileProxy": false,
  "browser": [{"name": "firefox", "minVersion": 120, "maxVersion": 130}],
  "userAgent": "custom-user-agent"
}

2. 销毁会话（scrappey_destroy_session）

正确关闭浏览器会话以释放资源。

{
  "session": "session_id_here"
}

3. 列出会话（scrappey_list_sessions）

列出当前用户的所有活动会话。

{}

响应：

{
  "sessions": [{"session": "abc123", "lastAccessed": 1234567890}],
  "open": 1,
  "limit": 100
}

4. 检查会话是否活动（scrappey_session_active）

检查指定会话当前是否处于活动状态。

{
  "session": "session_id_here"
}

5. 发送请求（scrappey_request）

发送基于浏览器的 HTTP 请求，并自动处理 JavaScript 挑战页面。

{
  "cmd": "request.get",
  "url": "https://example.com",
  "session": "session_id_here",
  "postData": {"key": "value"},
  "customHeaders": {"User-Agent": "custom-agent"},
  "cookies": "session=abc123",
  "proxyCountry": "Germany",
  "premiumProxy": true,
  "cloudflareBypass": true,
  "datadomeBypass": true,
  "automaticallySolveCaptchas": true,
  "alwaysLoad": ["recaptcha", "hcaptcha"],
  "screenshot": true,
  "cssSelector": ".product-title",
  "innerText": true,
  "includeLinks": true,
  "includeImages": true,
  "interceptFetchRequest": "https://api.example.com/data",
  "abortOnDetection": ["analytics.com", "tracking.js"],
  "whitelistedDomains": ["example.com"],
  "blockCookieBanners": true
}

6. 浏览器操作（scrappey_browser_action）

执行浏览器自动化操作。

{
  "session": "session_id_here",
  "url": "https://example.com",
  "cmd": "request.get",
  "browserActions": [
    {"type": "wait_for_selector", "cssSelector": "#login-form"},
    {"type": "type", "cssSelector": "#username", "text": "myuser"},
    {"type": "type", "cssSelector": "#password", "text": "mypassword"},
    {"type": "solve_captcha", "captcha": "turnstile"},
    {"type": "click", "cssSelector": "#submit", "waitForSelector": ".dashboard"},
    {"type": "execute_js", "code": "document.querySelector('.user-data').innerText"}
  ],
  "mouseMovements": true
}

支持的浏览器操作类型：

操作	描述
click	点击元素
type	在输入框中输入文本
goto	导航至 URL
wait	等待指定的毫秒数
wait_for_selector	等待元素出现
wait_for_function	等待 JavaScript 条件为真
wait_for_load_state	等待页面加载状态（domcontentloaded、networkidle、load）
wait_for_cookie	等待 Cookie 设置完成
execute_js	执行 JavaScript 代码
scroll	滚动至元素或页面底部
hover	将鼠标悬停在元素上
keyboard	按下键盘按键（enter、tab 等）
dropdown	从下拉列表中选择选项
switch_iframe	切换至 iframe
set_viewport	更改浏览器视口大小
if	有条件地执行操作
while	条件为真时循环执行操作
solve_captcha	解决各种验证码
remove_iframes	移除页面上的所有 iframe

支持的交互式挑战类型：

• turnstile - Cloudflare Turnstile
• recaptcha / recaptchav2 / recaptchav3 - Google reCAPTCHA
• hcaptcha / hcaptcha_inside / hcaptcha_enterprise_inside - hCaptcha
• funcaptcha - FunCaptcha/Arkose Labs
• perimeterx - PerimeterX
• mtcaptcha - MTCaptcha
• custom - 自定义图片验证码

7. 截图（scrappey_screenshot）

为网页截图。

{
  "url": "https://example.com",
  "session": "optional_session_id",
  "screenshotWidth": 1920,
  "screenshotHeight": 1080,
  "fullPage": true,
  "browserActions": [
    {"type": "wait", "wait": 2000}
  ],
  "premiumProxy": true
}

挑战页面处理

许多网站会先提供 JavaScript 挑战页面，然后才返回内容。Scrappey 会在真实浏览器中渲染这些页面，因此自动化请求能够收到最终页面。此服务兼容常见机器人管理系统提供的挑战页面：

• Cloudflare - Bot Management、Turnstile、挑战页面
• Datadome
• PerimeterX
• Kasada
• Akamai - Bot Manager
• Incapsula - Imperva

在每个请求中启用针对特定系统的处理：

{
  "cloudflareBypass": true,
  "datadomeBypass": true,
  "kasadaBypass": true
}

上述选项键（cloudflareBypass 等）是 Scrappey API 字段名称，为了保持兼容性，原样保留。

代理选项

{
  "proxy": "http://user:pass@ip:port",
  "proxyCountry": "UnitedStates",
  "premiumProxy": true,
  "mobileProxy": true,
  "noProxy": false
}

支持的国家/地区： UnitedStates、UnitedKingdom、Germany、France 等。

错误代码

此服务会提供详细的错误信息：

代码	描述
CODE-0001	服务端容量已满，请重试
CODE-0002	被 Cloudflare 拦截
CODE-0007	Turnstile/代理错误
CODE-0010	Datadome 代理被拦截
CODE-0024	代理超时
CODE-0029	打开的会话过多
CODE-0032	Turnstile 验证码失败

典型工作流

1. 创建会话：

{"name": "scrappey_create_session"}

2. 导航并交互：

{
  "name": "scrappey_browser_action",
  "session": "returned_session_id",
  "url": "https://example.com/login",
  "cmd": "request.get",
  "browserActions": [
    {"type": "type", "cssSelector": "#username", "text": "myuser"},
    {"type": "type", "cssSelector": "#password", "text": "mypass"},
    {"type": "click", "cssSelector": "#login-btn", "waitForSelector": ".dashboard"}
  ]
}

3. 提取数据：

{
  "name": "scrappey_request",
  "cmd": "request.get",
  "url": "https://example.com/data",
  "session": "returned_session_id",
  "cssSelector": ".product-list"
}

4. 清理：

{
  "name": "scrappey_destroy_session",
  "session": "returned_session_id"
}

最佳实践

1. 重复使用会话，以便相关请求保持状态
2. 完成后销毁会话，以释放资源
3. 使用高级代理，以获得更可靠的连接
4. 为提供挑战页面的网站启用自动挑战处理
5. 在操作之间设置适当的等待时间，以便页面有时间加载
6. 监控会话限制，避免达到上限

负责任地使用

此服务是用于基于浏览器的自动化和数据提取的开发工具。仅将其用于合法且经授权的用途，例如：

• 测试和监控由你拥有或运营的应用程序和集成
• 收集你获准访问的数据

访问第三方网站时，请遵守各网站的服务条款、robots 指令和速率限制，尊重个人数据和版权，并遵守所有适用法律。你须对如何使用此服务及你的 Scrappey 账户负责。

部署

Smithery 部署

# Build
npm run build

# Deploy via Smithery CLI
npx @anthropic/smithery-cli deploy

Docker

docker build -t scrappey-mcp .
docker run -e SCRAPPEY_API_KEY=your_key scrappey-mcp

资源

• 在 Smithery 上试用
• Scrappey 文档
• 获取 Scrappey API 密钥

许可证

MIT 许可证