Fouradata Mcp

FourA MCP

为 AI Agent 提供可靠的网页访问能力。

为你的 Agent 提供一个公开 URL。无论页面需要快速 HTTP 请求、代理轮换，还是完整的浏览器会话，FourA 都会返回内容。

从 foura_auto 开始：输入一个 URL，即可获得类型化内容。它会选择合适的抓取方式，并为你处理常见的拦截。若想明确控制请求路径，可使用 foura_single、foura_proxy 或 foura_browser。

简单上手	访问难以抓取的页面	构建可预测的 Agent 工作流
适用于大多数 URL 的默认工具	HTTP、代理轮换和完整浏览器渲染	类型化输出、稳定的错误代码和六个现成提示词

内置工作流涵盖产品信息提取、文章整理、价格监控、端点检查和批量 URL 抓取。

可在 Claude Desktop、Claude Code、Cursor、Windsurf、VS Code 或任何 MCP 客户端中使用。可在本地运行 npm 包，也可使用同一个 FourA API 密钥连接到托管的 Streamable HTTP 端点。

获取 API 密钥 | 阅读 MCP 文档 | 在 npm 上查看软件包

一键安装：

两个按钮都会预填配置，并使用 YOUR_FOURA_API_KEY 占位符——请将其替换为你的密钥。也可以手动配置：claude mcp add foura -- npx -y @fouradata/mcp（请先在 env 中设置 FOURA_API_KEY）。下文提供各客户端的完整配置说明。

快速开始 - 本地 stdio（推荐用于 Claude Desktop）

在 foura.ai/dashboard/#api-keys 创建或查看 API 密钥（格式为 pk_live_...）。然后将以下内容放入 MCP 客户端的配置中：

{
  "mcpServers": {
    "foura": {
      "command": "npx",
      "args": ["-y", "@fouradata/mcp"],
      "env": {
        "FOURA_API_KEY": "pk_live_..."
      }
    }
  }
}

Claude Desktop 注意事项：编辑配置文件前，请完全退出 Claude Desktop（macOS 上按 Cmd+Q）。如果应用仍在运行，退出时会用内存中的配置覆盖你的修改。

npx 命令会在首次启动时下载软件包，并将其作为 MCP 客户端的子进程运行。无需全局安装。相同的 JSON 可用于不同的 MCP 客户端；只有配置文件的位置会改变：

客户端	配置文件位置
Claude Desktop（macOS）	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop（Windows）	%APPDATA%\Claude\claude_desktop_config.json
Claude Code	claude mcp add foura -- npx -y @fouradata/mcp（先在 env 中设置 FOURA_API_KEY）
Cursor	~/.cursor/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json
VS Code（MCP 扩展）	工作区中的 .vscode/mcp.json

重启客户端后，foura_auto、foura_single、foura_proxy、foura_browser 会显示在工具列表中，此外 /prompts 下还会显示六个提示词。

快速开始 - 托管式（Streamable HTTP）

如果客户端支持 Streamable HTTP 传输，可将其指向托管端点，而不是运行本地子进程：

{
  "mcpServers": {
    "foura": {
      "url": "https://mcp.foura.ai/mcp",
      "headers": {
        "Authorization": "Bearer pk_live_..."
      }
    }
  }
}

对于 Claude Desktop，请使用上面的 stdio 配置。你也可以通过 mcp-remote 桥接托管端点：

{
  "mcpServers": {
    "foura": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.foura.ai/mcp", "--header", "Authorization: Bearer pk_live_..."]
    }
  }
}

工具

foura_auto 是默认工具——提供一个 URL，它就会返回内容，并自动选择获取方式。其他三个工具可让你直接控制 HTTP、代理轮换和浏览器渲染。

根据 MCP 规范，这四个工具都标记为 readOnlyHint: true 和 openWorldHint: true。客户端可在决定如何呈现或批准工具调用时使用这些注释。

每个响应都包含人类可读的文本（content）以及经过工具 outputSchema 验证的类型化 structuredContent JSON 对象。你的 Agent 会获得可预测的响应约定，而无需解析文本。

foura_auto - 智能获取（默认）

提供一个 URL，即可获取内容。当你不想在 HTTP、代理轮换和浏览器渲染之间做选择时，优先使用此工具。它能处理常见的机器人验证，并保持客户端接口精简，无需调整代理尝试参数。

{
  "url": "https://example.com",
  // optional: a substring the real page must contain, so auto can tell a
  // real page from a challenge page on protected targets
  "validate": { "data": { "accept": ["Example Domain"] } }
}

客户端接口刻意保持精简：url（必填），以及可选的 method、headers、data、validate、returnSession（默认值为 true）、forceProxy（默认值为 true）、timeout_ms（5000-180000，默认值为 120000）、ignoreProxies、exitClass（standard 或 premium，与 foura_proxy 相同）。

structuredContent 结构：{status, headers, data, meta, session}。meta 始终存在，格式为 {rung, solved, attempts, credits}，因此你的 Agent 可以了解请求是如何完成的，以及使用了多少积分。默认会返回 session（{proxy, cookies, userAgent}），供后续请求使用（将 session.proxy 传入 proxy 字段）。发送 returnSession: false 可省略它。auto 没有 total_time 字段。

exitClass: "premium" 可让 auto 在标准出口池无法访问页面时升级到高级出口，结果中的 exitClass 会说明实际使用的出口类别。首先使用标准出口池；套餐中的高级流量用完后，调用会继续使用标准出口池，并报告 standard。两种类别都不表示错误。对于不包含高级出口的套餐，调用会被拒绝，并返回 code: "plan_limit_premium"。exitClass: "standard" 可让 auto 不使用高级出口。

foura_single - 快速 HTTP

发送一个 HTTP 请求并返回响应。适用于静态页面、JSON API 和服务器渲染的 HTML。unblocker 默认为 true，因此请求已携带完整的浏览器标头集；将其设为 false 可发送普通 HTTP 请求。

{
  "method": "GET",
  "url": "https://example.com"
}

支持自定义标头、请求正文、各阶段超时、重定向控制、JSON 自动解析、二进制缓冲区模式，以及内置的响应验证（validate.status.accept、validate.data.fail 等）。如果 foura_single 返回的结果被拦截——状态码为 403/429、验证码页面、质询响应标头或已知的质询标题——请尝试其他浏览器配置（见下文），然后升级到 foura_proxy。从 maxTries: 5 开始；受保护的目标可能需要 25-30 次。如果页面还需要 JavaScript 才能渲染，请将 foura_proxy 返回的 proxy ID 传给 foura_browser.proxy。

structuredContent 的结构：{status, headers, data, total_time, ...}。当目标运行了机器人检测时，响应还会包含 defense；defense.solved: false 表示正文可能是质询页面，而不是你请求的内容。

选择要呈现的浏览器

默认情况下，请求会呈现最新版本的 Google Chrome。有些目标接受一种浏览器，却拒绝另一种，因此 foura_single 和 foura_proxy 允许你选择：

{
  "method": "GET",
  "url": "https://example.com",
  "browser": "Firefox",
  "os": "Windows"
}

• browser - Chrome、Edge、Safari、Firefox 或 Tor。
• os - Windows、macOS、Android 或 iOS。家族名称接受该家族的任意版本；目录中的精确标签可进一步缩小范围。
• version - 目录中为该浏览器列出的任意版本。符合条件的版本有多个时，优先选择最新版本。
• profile - 已有配置时，可使用目录中的精确 ID。

完整目录公开发布于 api.foura.ai/api/profiles，无需密钥；其中的 default 字段指出未指定配置时请求使用的配置。选择配置需要启用 unblocker，它默认已启用。不存在的组合会返回错误并列出可用选项，因此请求绝不会在未通知你的情况下悄悄使用你未选择的浏览器。

foura_proxy - 失败时重试的轮换代理

目标形态与 foura_single 相同，但请求会通过轮换代理发送，并在失败时自动重试。直接请求被拦截或目标要求使用特定出口国家时，请使用它。

{
  "maxTries": 5,
  "exitCountries": ["CZ", "GB"],
  "request": {
    "method": "GET",
    "url": "https://example.com/pricing",
    "browser": "Chrome",
    "os": "Windows"
  }
}

structuredContent 会添加 proxy（成功的代理的编码 ID）和 total（包含代理选择和重试的总耗时）。如果轮换过程中必须切换到另一个浏览器才能获得响应，profile 会指出最终选用的目录配置；下次调用时将其作为 profile 传入，即可使用相同的浏览器。exitCountries 为可选项：值会经过去空格、转为大写并去重；出口未知的代理会被排除；请求绝不会回退到未请求的国家。代理选择会使用最新可用的国家元数据，通常每十分钟内更新一次；范围限定请求成功时会将该值作为 exitCountry 返回。如果没有符合条件的代理，结果会使用 code: "no_eligible_proxy"。

内部的 request 接受与 foura_single 相同的浏览器配置字段：browser、os、version 或精确的 profile。

exitClass - 用于标准代理池无法访问的目标。 设置 exitClass: "premium"，请求便可升级到高级出口，而不只是在标准代理池中轮换。这是一项许可，而非指令：标准代理池仍会竞速获取响应，通常会先成功；如果请求在尝试任何高级出口前就已获得响应，则不会消耗高级流量。一旦尝试过高级出口，该出口承载的流量就会计入你的高级额度，即使尝试失败也是如此；如果另一个出口先获得响应，仍在运行的尝试会被停止且不计入额度。响应会返回 exitClass，值为 premium 或 standard，因此你可以查看每个请求由哪类出口处理。计划中的高级流量用完后，standard 也会作为结果返回；这是正常结果，并非错误。exitClass: "standard" 会完全禁止升级。没有高级出口的计划会拒绝此次调用，并返回 code: "plan_limit_premium"。

attemptReport - 轮换尝试耗尽的原因。 每个失败的 foura_proxy 结果都会在错误旁附带此字段。summary 是一句话；下面的计数会区分需要采取不同处理方式的原因：noResponse（出口没有响应）、defense（识别到机器人验证，vendors 中会列出其名称）、contentRejected（HTTP 200，未触发机器人验证，但被你自己的 validate.data 拒绝）、statusRejected 和 other。profilesTried 会按首次使用顺序列出任务发送请求时使用的浏览器，其中 default 表示请求完全按原样发送。contentRejected 较高意味着页面已成功返回，但被你自己的规则丢弃：使用 foura_single 获取其中一个页面且不传入 validate，查看页面内容，然后重写规则。

对于难以处理的 WAF 挑战，请使用 maxTries: 25-30。对于国家地区允许列表，请设置 exitCountries，而不是增加尝试次数。如果目标需要 JavaScript 渲染，请将返回的 proxy ID 传给 foura_browser.proxy。

foura_browser - 完整浏览器会话

真实的浏览器会话。JavaScript 会运行，DOM 会完成渲染，Cookie 会随响应返回。页面是单页应用、内容在首次绘制后延迟加载，或者存在需要真实浏览器才能通过的反机器人挑战时，请使用它。

{
  "url": "https://example.com/spa",
  "timeout_ms": 15000,
  "checkText": "data-table"
}

当 HTTP 响应不足以满足需求时，请使用此工具。导航完成后，checkText 会验证渲染后的 HTML；它不会等待或轮询。如果缺少指定子字符串，调用会失败并返回错误封装。这可用于捕获那些返回 200、但未包含所需内容的页面。unblocker 默认值为 true，会在过程中处理支持的反机器人或验证码挑战。将其设为 false，即可原样返回页面加载结果，包括其中的挑战内容。

structuredContent 的结构刻意区别于 single/proxy：{status, headers (object, not array), body (not data), cookies (full browser cookie shape), userAgent}。

内置提示词

你的 MCP 客户端中，/prompts 下提供了六个工作流模板。它们可以编排一个或多个工具，无需你逐步说明操作步骤。

提示词	参数	功能
smart_fetch	url, must_contain?, extract?	选择方法、处理机器人防护，并返回或提取内容
scrape_product_page	url	在浏览器会话中提取标题、价格、图片、库存和 SKU，并以 JSON 格式返回
extract_article	url	获取文章；如有需要，通过代理重试并移除页面边框内容
monitor_pricing	url, target_price?	获取当前价格并与目标价格比较
check_endpoint_health	url, expected_text?	验证可访问性、状态、内容和耗时
bulk_fetch_urls	urls（逗号分隔）	并行获取 URL，对被拦截的请求重试，并返回元数据

每个提示词都会作为模板化的用户消息提供，由你的大模型使用适当的工具执行。只有调用提示词时，完整提示词文本才会进入上下文。

完整方案文本和手动备用提示词：foura.ai/docs/mcp/recipes。完整错误代码列表请参阅 foura.ai/docs/mcp/errors。

身份验证

在 stdio 模式下使用 FOURA_API_KEY，或在托管端点中使用 Authorization: Bearer pk_live_... 标头。一个密钥即可验证所有四个工具。

密钥在控制面板中管理，你可以在其中创建、查看、轮换或停用密钥。完整的密钥管理指南请参阅 foura.ai/docs/getting-started/authentication。

错误封装——用于 Agent 重试的类型化契约

每个错误（isError: true）都包含一个 structuredContent 封装，至少包含以下三个字段：

{
  "service": "auto" | "single" | "proxy" | "browser",
  "code": "ssrf_blocked" | "auth_failed" | "rate_limited" | ...,
  "error": "Human-readable message"
}

如果上游返回了状态码，你还会收到 status（HTTP 代码）；对于限流或容量错误，FourA API 封装还会添加 retryAfter、current.{concurrency, rpm}、limits.{maxConcurrency, maxRpm}。

code	发生时机	重试是否安全？
ssrf_blocked	目标解析为私有或保留地址	否——更改 URL
upstream_non_json	上游返回了格式错误的正文	可能——进行调查
bad_request（400）	FourA 拒绝了输入格式	否——修正参数
auth_failed（401）	密钥缺失、无效或已停用	否——修正密钥
forbidden（403）	已通过身份验证，但无权执行	否
not_found（404）	目标或端点不存在	否
rate_limited（429）	达到每分钟请求数上限	是——等待 retryAfter
at_capacity（503）	达到并发上限	是——等待 retryAfter
service_disabled（503）	维护时段	是——等待 retryAfter
service_unavailable（503）	通用 503 错误	是——短暂退避
upstream_error（>=500）	上游 5xx 错误	是——指数退避
upstream_client_error（4xx）	其他 4xx 错误	通常不安全
no_eligible_proxy	没有代理符合请求的 exitCountries	否——更改国家范围
plan_limit_*（403/429）	你自己的 FourA 套餐拒绝了调用，而非目标拒绝	只有等待 retryAfter 才能解除——见下文

plan_limit_ 代码会指出你的套餐中哪个限制拒绝了调用：credits、bandwidth、rate、concurrency、browser_daily、premium 或 feature。这不是目标在拦截你，因此通过其他工具重试相同任务，只会白白消耗剩余额度。如有 retryAfter，请等待其时间结束；或者更改套餐。

LLM Agent 可以直接读取 code 来实现重试逻辑，无需解析说明文字。规范参考：foura.ai/docs/api/errors。

每个结果都包含的内容

除了工具自身的字段外，每个结果还会报告本次调用的费用以及追踪方式：

• credits - 本次调用消耗的额度，包括失败调用，因为无论结果如何，工作都已完成；
• request_id - FourA 为本次调用生成的 ID。提交支持请求时请附上它；
• exitClass - 当高级出口为本次调用提供服务时，值为 premium。在 foura_single 和 foura_browser 中，如果 proxy 重放了由 foura_proxy 或 foura_auto 找到的高级出口，就会发生这种情况；在 foura_proxy 和 foura_auto 中，只要请求指定了 exitClass，就会报告该值。

组合使用工具 - 复用同一个出口

这些底层工具可以组合使用。foura_proxy 会返回其所用出口的 base36 ID。将该 ID 传入 foura_single.proxy 或 foura_browser.proxy，即可在下一次请求中复用同一个出口。

// 1. Find a working exit. Difficult protected targets may need maxTries:25-30.
const r = await foura_proxy({
  maxTries: 30,
  request: { method: "GET", url: "https://probe.example.com" }
});
// Returns { status: 200, proxy: "4DZ3VE", ... }

// 2. Reuse it for follow-up HTTP
await foura_single({ method: "GET", url: "https://target/api", proxy: r.proxy });

// 3. Or render JavaScript through the same exit.
await foura_browser({ url: "https://target/spa", proxy: r.proxy });

对于受保护的 JavaScript 页面，请先用 foura_proxy 找到可用线路，再调用 foura_browser。如果先从浏览器开始，真实内容加载前可能会返回挑战页面。

若要在下一次 foura_proxy 调用中选择其他代理，请将上一个 ID 作为 ignoreProxies: ["4DZ3VE"] 传入。foura_single 和 foura_browser 中的 proxy 字段也接受原始 URL（http://host:port、socks5://...），前提是你有自己的代理列表。

大型响应 - offload_large（默认值：内联）

默认情况下（自 v0.2.0 起），无论响应正文大小如何，都会在 structuredContent 中直接返回完整正文。这适用于所有 MCP 客户端。

如果你的客户端支持 MCP resources/read（并且你想节省大型页面所消耗的令牌），请在每次工具调用中传入 offload_large: true。对于 50 KB 或更大的响应，会以 resource_link 形式返回；客户端仅在需要时获取正文。资源会保留一小时。

{
  "method": "GET",
  "url": "https://en.wikipedia.org/wiki/Web_scraping",
  "offload_large": true   // opt in for token savings
}

不同客户端对 MCP 资源链接的支持各不相同。如果你的客户端无法读取 resource_link 块，请将 offload_large 保持为默认值 false。

只有创建已卸载资源的 API 密钥才能读取该资源。

限制与负责任的使用

• 拒绝访问私有目标。 MCP 层会拦截发往私有或保留地址的请求。只有发往公共互联网主机的请求才会被转发。
• 速率限制由 FourA API 按服务执行，包括并发数和 RPM。详情请见 foura.ai/docs/api/rate-limits。

请仅使用 FourA 访问你获准访问的公开内容，并遵守目标网站的条款及适用法律。

自行运行

使用 npx -y @fouradata/mcp 直接从 npm 运行 stdio 服务，或者构建随附的 Dockerfile 以使用 Streamable HTTP 传输。

可配置的环境变量：

变量	默认值	用途
PORT	3076	HTTP 监听端口
FOURA_API_BASE	https://api.foura.ai/api	上游 FourA REST 基础 URL
FOURA_MCP_PAYLOADS_DIR	/data/payloads	在磁盘上缓存 50 KB 或更大响应的位置

有关本地构建和测试工作流，请参阅 DEVELOPMENT.md。

许可证

MIT。请参阅 LICENSE。

链接

• FourA（网页抓取 API）：https://foura.ai
• MCP 服务页面：https://foura.ai/mcp
• 源代码（GitHub）：https://github.com/fouradata/mcp
• npm 包：https://www.npmjs.com/package/@fouradata/mcp
• API 文档：https://foura.ai/docs
• MCP 服务参考：https://foura.ai/docs/mcp/server
• MCP 错误代码：https://foura.ai/docs/mcp/errors
• MCP 配方：https://foura.ai/docs/mcp/recipes
• REST API 错误：https://foura.ai/docs/api/errors
• MCP 规范：https://modelcontextprotocol.io
• 获取密钥：https://foura.ai/dashboard/#api-keys