solvegate-mcp

solvegate-mcp

一个 MCP 服务，可让 Agent 处理 Cloudflare Turnstile：检查页面是否有 Turnstile，并在有的情况下解除它。

提供三个工具。其中一个无需账户。

工具	功能	是否需要密钥
inspect_page	获取 URL 并报告页面是否启用了 Cloudflare Turnstile、其 sitekey、渲染方式、data-* 配置，以及页面是否为整页 WAF 挑战而非小组件	否
solve_turnstile	解除 Turnstile 或 Turnstile WAF 挑战并返回令牌	是
get_solve	按 ID 获取求解结果——免费，不会重复计费	是

安装

npx solvegate-mcp

在 Claude Desktop／任何 MCP 客户端中，将以下内容添加到配置中：

{
  "mcpServers": {
    "solvegate": {
      "command": "npx",
      "args": ["-y", "solvegate-mcp"],
      "env": { "SOLVEGATE_API_KEY": "sk_test_…" }
    }
  }
}

即使不设置 SOLVEGATE_API_KEY，inspect_page 仍可使用。这是有意为之：你可以先了解此服务的功能，再决定是否注册。

在 solvegate.io 获取密钥。免费的 sk_test_ 沙盒密钥无需银行卡，并会立即返回确定性令牌，适合用于接入测试，而且不会解除真实的验证。

为什么要提供 inspect_page

使用求解器时，最常见的错误就是本该先检查，却直接调用了求解器。大多数情况都属于以下三种：

• 页面上的是 reCAPTCHA 或 hCaptcha，而不是 Turnstile。 这些是不同供应商提供的不同产品。本服务无法处理它们，SolveGate 也不能——inspect_page 会明确指出这一点，而不是让你直到收到 422 才发现。
• 这是 WAF 挑战，而不是小组件。 Cloudflare 的整页拦截页没有 data-sitekey，因为挑战属于区域规则，而不是嵌入式小组件。页面上没有可读取的信息，且其验证类型是 waf，而不是 turnstile。
• sitekey 是页面加载后由脚本渲染的。 这种情况下，它根本不在已提供的 HTML 中，工具会如实说明，而不是猜测。

检查是免费的，大约需要一秒，而且往往检查结果就是全部答案。

它不会告诉你的信息

小组件模式。 Managed、non-interactive 和 invisible 模式存储在拥有该 sitekey 的 Cloudflare 账户中的小组件上。页面只包含密钥，因此任何工具都无法从页面源代码中读取模式——本工具也不例外，任何声称可以做到这一点的工具都不例外。

这不会影响求解：这三种模式都会使用相同的请求。提供 sitekey 和页面 URL，返回令牌。

唯一的例外是 Cloudflare 公布了小组件类型的五个官方虚拟 sitekey。inspect_page 会报告这些信息；如果在页面上发现其中一个，就能知道一些有用信息——你查看的是预发布版本，而不是生产版本。

配置

变量	默认值	功能
SOLVEGATE_API_KEY	—	你的密钥。沙盒使用 sk_test_，真实验证使用 sk_live_。
SOLVEGATE_BASE_URL	https://api.solvegate.io	API 基础 URL。
SOLVEGATE_SITE_URL	https://solvegate.io	inspect_page 的运行地址。
SOLVEGATE_TIMEOUT_MS	30000	单次请求的超时时间。
SOLVEGATE_MAX_WAIT_MS	60000	solve_turnstile 等待待处理求解的时长。

密钥从环境变量读取，绝不会作为工具参数——工具参数对模型可见，并会出现在对话记录中。

行为说明

底层采用异步求解。 solve_turnstile 会通过 async: true 创建求解任务并轮询，而不是在整个尝试期间保持连接打开。Agent 的工具调用有自身无法控制的超时时间，而同步求解会让缓慢的验证关卡看起来像是工具失效了。这也意味着，即使此处超时，你仍会获得一个求解 ID：错误信息中会列出该 ID，get_solve 会继续获取结果，而不是丢失已计费的求解任务。

错误是结果，而不是异常。 所有失败都会以 isError 结果返回，并携带 SolveGate 自身的 error.code——balance_empty、unknown_sitekey、rate_limited、forbidden_target。模型可以据此采取行动，但堆栈跟踪毫无用处。

令牌只能使用一次，且有效期很短。 expiresAt 是 Unix 秒数；过期后，Cloudflare 将不再接受该令牌，求解记录也就只是一条记录。请在提交时获取令牌。

信任令牌前先检查 mode。 sk_test_ 密钥会返回 mode: "sandbox"，而沙盒令牌无法通过真实的验证关卡。设置此字段是为了让生产配置中的测试密钥明确报错，而不是悄无声息地出错。

可接受的使用方式

只对你拥有或获准测试的属性进行求解。本工具适用于因验证挑战而不断失败的端到端测试、针对自有预发布环境的 CI，以及对自有生产环境进行合成监控。 可接受使用政策是具有约束力的版本；无论任何 Agent 如何请求，拒绝名单上的目标都会返回 403 forbidden_target。

开发

npm install
npm run build
npm test          # spawns the built server and speaks MCP to it
OFFLINE=1 npm test  # skips the two tests that reach the network

测试会通过真实的 stdio 传输驱动，而不是直接调用工具回调。这是有意为之：SDK 在注册时拒绝的架构，或意外写入 stdout 的内容——由于 stdout 就是传输通道，这会破坏传输——只有在实际通过协议与其通信时才会显现。

链接

• SolveGate API 参考
• OpenAPI 规范
• Turnstile 检查器 — 在浏览器中执行与本服务相同的检查
• Turnstile 错误索引

MIT。