1. Pi Agent 为什么需要 Scrapeless MCP 服务器Pi Agent 是一个刻意做减法的终端编码代理。它默认只带四个工具read、write、edit、bash。这个设计的好处是上下文窗口占用极低启动快模型注意力不会被几十个用不到的工具定义稀释。但代价也很直接——它没有内置联网能力推理完全受限于底层模型的训练数据。我试过让 Pi 生成某个前端库的最新用法它给出的 API 在训练截止时是对的但那个库上个月刚改了签名。这类问题在快速迭代的生态里非常常见网络框架、AI 工具链、基础设施组件文档和发布说明几乎每周都在变。Pi 无法自己去读当前文档、变更日志或发布页面只能从记忆里猜。解决办法是给 Pi 接一个暴露网络工具的 MCP 服务器。Scrapeless MCP 服务器把云浏览器、搜索和抓取 API 包装成标准 MCP 工具覆盖 google_search、google_trends、16 个 browser_* 浏览器自动化工具以及 scrape_html、scrape_markdown、scrape_screenshot 三个无状态抓取工具一共 21 个。它支持两种传输stdio 用npx -y scrapeless-mcp-server作为子进程启动适合终端代理可流式 HTTP 指向https://api.scrapeless.com/mcp适合无法执行 npx 的云主机。Pi 本身不直接支持 MCP这是作者的有意选择——像 Playwright MCP 那样暴露 21 个工具会消耗约 13.7k tokenChrome DevTools MCP 更是接近 18k几个服务器连起来上下文就没了。社区方案 pi-mcp-adapter 只暴露一个约 200 token 的代理工具服务器默认懒惰启动只有代理真正调用工具时才拉起闲置 10 分钟后断开。工具元数据缓存到磁盘搜索和描述不需要实时连接也能工作。所以整条链路是你在终端给 Pi 一个提示Pi 通过 pi-mcp-adapter 调用 Scrapeless MCP 服务器服务器驱动云浏览器抓取实时页面把干净的 Markdown 或排名结果返回给 PiPi 再基于刚抓到的内容生成代码。输出不再是过时记忆里的最佳猜测而是基于当前在线版本。这套组合适合谁适合已经在用 Pi 做日常编码、又经常需要查最新文档或抓取公开页面数据的人。如果你只是偶尔写点不依赖外部库的脚本那 Pi 原生四工具就够了。但只要涉及联网检索、区域化数据、需要 JavaScript 渲染的页面接上 Scrapeless MCP 就是刚需。2. TaoToken 统一 Key 通道的前置准备在配置 MCP 之前先把模型通道理顺。Pi 支持 Anthropic、OpenAI、Google、Mistral、Groq 等多家提供商但每家一个 Key、一套计费、一套限流管理起来很碎。TaoToken 提供统一 Key 通道一个 Key 走多家模型Base URL 固定鉴权方式一致省去在多个控制台之间切换的麻烦。你需要准备三样东西。第一是 Node.js 18 或更高版本Pi Agent 和 pi-mcp-adapter 都依赖它如果你用的是 Pi 的 Gemini CLI 变体需要 Node 20 以上。第二是 Scrapeless 的 API Key在 app.scrapeless.com 注册后到设置里的 API 密钥页面复制新账户自带免费的抓取浏览器运行时。第三是 TaoToken 的 API Key到控制台创建即可。TaoToken 的接入信息如下后面配置 Pi 的模型提供商会用到项目值Base URLhttps://taotoken.net/apiAPI Key在控制台 API Keys 页面创建Model ID按需选择如 claude-sonnet-4-5、gpt-4o 等接入文档https://taotoken.net/doc控制台https://taotoken.net/consoleAPI Keys 页面https://taotoken.net/api-keys这里要强调一个容易踩的坑Scrapeless MCP 服务器读取的环境变量名是SCRAPELESS_KEY不是SCRAPELESS_API_KEY。Scrapeless 的其他产品面独立 CLI、代理技能用的是SCRAPELESS_API_KEY但 MCP 服务器是个例外。名字写错服务器启动后拿不到凭证工具调用会直接失败。这个细节后面在.mcp.json里会再出现一次。TaoToken 的 Key 和 Scrapeless 的 Key 是两套独立凭证各管各的。TaoToken 管模型推理通道Scrapeless 管抓取和浏览器通道。不要混用也不要把 Scrapeless 的 Key 填到模型配置里。如果你还没装 Pi先执行全局安装npm install -g mariozechner/pi-coding-agent验证一下pi --version发布时 Pi 二进制对应mariozechner/pi-coding-agent0.73.1 版本。装完 Pi 再装 MCP 适配器pi install npm:pi-mcp-adapter适配器发布时是 2.6.1 版本装完重启 Pi 生效。它会注册一个mcp代理工具和/mcp斜杠命令用于交互式管理服务器。关于 TaoToken 的 Coding Plan如果你打算长期用 Pi 做编码和 Agent 任务可以了解一下它针对高频编码场景做了额度优化。模型对话入口在 https://taotoken.net/models 接入文档在 https://taotoken.net/doc API Keys 在 https://taotoken.net/api-keys 。这些链接后面 CTA 部分还会按场景分流。3. 可复制的 .mcp.json 与模型配置pi-mcp-adapter 读取标准 MCP 配置文件按以下优先级查找~/.config/mcp/mcp.json用户全局共享、Pi代理目录/mcp.jsonPi 全局覆盖通常是~/.pi/agent/mcp.json、.mcp.json项目本地共享、.pi/mcp.jsonPi 项目覆盖。日常开发用项目本地的.mcp.json最方便跟着仓库走团队共享也直接。在项目根目录创建.mcp.jsonstdio 形式如下{ mcpServers: { scrapeless: { command: npx, args: [-y, scrapeless-mcp-server], env: { SCRAPELESS_KEY: YOUR_SCRAPELESS_KEY } } } }把YOUR_SCRAPELESS_KEY换成第 2 步复制的 Scrapeless Key。首次运行时npx -y scrapeless-mcp-server会自动下载包并通过标准输入启动服务器不需要单独安装命令。如果你在无法调用 npx 的云主机上跑 Pi改用可流式 HTTP 传输{ mcpServers: { scrapeless: { url: https://api.scrapeless.com/mcp, headers: { x-api-token: YOUR_SCRAPELESS_KEY } } } }两种形式用同一个 Scrapeless Key暴露同样的 21 个工具。stdio 是工作站的默认选择HTTP 是云主机的默认选择。接下来配置 Pi 的模型提供商走 TaoToken 统一通道。启动 Pipi输入/login选择 API Key 方式把 TaoToken 的 Key 粘贴进去。然后在模型配置里指定 Base URL 为https://taotoken.net/apiModel ID 按你需要的模型填。如果你更习惯用配置文件可以在 Pi 的配置目录里写 settings 片段把 provider 的 baseURL 指向 TaoTokenapiKey 填 TaoToken Keymodel 填对应 Model ID。三件套就是 Base URL、Key、Model ID缺一不可。这里有个细节pi-mcp-adapter 的代理工具默认只暴露一个mcp工具约 200 token。如果你希望某些高频工具直接出现在系统提示里可以在 scrapeless 条目加directTools{ mcpServers: { scrapeless: { command: npx, args: [-y, scrapeless-mcp-server], env: { SCRAPELESS_KEY: YOUR_SCRAPELESS_KEY }, directTools: [google_search, scrape_markdown] } } }直接工具每个在系统提示里花约 150 到 300 token选代理最常用的那几个就行别全开。全开就回到了适配器想避免的上下文膨胀问题。配置写完后.mcp.json里的mcpServers对象是标准 MCP 配置封装Claude Desktop、Cursor、Codex CLI、Gemini CLI、Windsurf、VS Code Copilot Chat 都能读只是某些客户端的路径或文件名略有不同。同一段 Scrapeless 配置在它们之间可以共享。4. 启动服务器并验证一次联网抓取配置就绪后启动 Pi你应该在扩展列表里看到 pi-mcp-adapter。输入/mcp打开 MCP 面板scrapeless 服务器会列出来但初始可能显示0/21因为服务器是懒惰的连接还没打开。用方向键高亮该行按CtrlR重新连接或者直接调用任意 Scrapeless 工具触发懒惰连接。连接成功后终端底部显示MCP: 1/1 servers。先确认工具能被发现在 Pi 里执行mcp({ search: scrapeless })结果里应该能看到 google_search、google_trends、browser_* 和 scrape_* 系列工具。按 Esc 关闭面板。现在跑一个真实的端到端任务。给 Pi 这样的提示在网上搜索官方 axios npm 文档抓取最相关的页面并生成一个有效的 JavaScript 示例以正确的错误处理方式发出 GET 请求。将其保存为 axios-example.js。Pi 会先调用scrapeless_google_search返回带标题、URL 和官方文档片段的排名结果列表。然后它挑出最相关的 URL调用scrapeless_scrape_markdown以干净的 Markdown 提取页面——云浏览器负责 JavaScript 渲染和反检测处理Pi 拿到的是提取后的内容而不是原始 HTML。在上下文里看到文档后Pi 基于刚读到的 API 版本生成axios-example.js。生成的文件大致长这样async function fetchPost() { try { const response await axios.get(https://jsonplaceholder.typicode.com/posts/1); console.log(状态:, response.status); console.log(标题:, response.data.title); console.log(正文:, response.data.body); } catch (error) { if (error.response) { console.error(状态:, error.response.status); console.error(数据:, error.response.data); } else if (error.request) { console.error(未从服务器收到响应); } else { console.error(请求设置错误:, error.message); } } }运行验证npm install axios node axios-example.js你会看到状态码、标题和正文打印出来。这一步证明整条链路通了提示进入 PiPi 经 pi-mcp-adapter 调用 Scrapeless MCP 服务器服务器驱动云浏览器抓取结果回到 PiPi 基于实时数据生成可运行代码。如果你想直接看 MCP 服务器的 tools/list 响应格式它大致是这样字段值为示例{ tools: [ { name: google_search, description: 通用信息搜索引擎, inputSchema: { type: object, properties: { q: { type: string, default: 最新新闻头条 }, gl: { type: string, default: us }, hl: { type: string, default: en } } } }, { name: scrape_markdown, description: 抓取一个URL并以Markdown格式返回其内容, inputSchema: { type: object, properties: { url: { type: string, format: uri } }, required: [url] } }, { name: browser_create, description: 创建一个新的云浏览器会话 }, { name: browser_goto, description: 在现有会话中导航到一个URL }, { name: browser_get_html, description: 返回当前页面的渲染HTML } ] }实际有 21 个工具这里只列了代表性的几个。google_search 加 scrape_markdown 是最常见的组合先搜索找到页面再抓取阅读。browser_* 工具留给需要登录、点击或分页的流程。5. 常见报错排查对照接入过程中会遇到几类典型报错逐个对照处理。401 未授权。如果模型调用返回 401检查 TaoToken 的 Key 是否填对、是否过期Base URL 是否为https://taotoken.net/api。如果 Scrapeless 工具调用返回 401检查.mcp.json里的环境变量名是不是SCRAPELESS_KEY值是不是完整的 Key。名字写成SCRAPELESS_API_KEY是最常见的错误服务器读不到就报未授权。local proxy failed。这个报错通常出现在网络层说明请求没能到达目标端点。检查你的 Base URL 是否写成了带路径的完整地址TaoToken 的 API 端点是https://taotoken.net/api不要多加斜杠或路径。如果用的是 HTTP 传输的 Scrapeless确认https://api.scrapeless.com/mcp可达。reading choices 相关报错。这类错误一般出现在模型返回结构不符合预期时常见于 Model ID 填错或模型不支持当前调用格式。确认你在 TaoToken 通道里选的 Model ID 是有效的并且该模型支持工具调用。换一个已知支持 function calling 的模型试试。OAuth 相关报错。如果你在/login时选了订阅方式而不是 API Key可能会走到 OAuth 流程。走 TaoToken 统一 Key 通道时应该选 API Key 方式避免 OAuth 回调配置问题。如果误入 OAuth退出重新/login选 API Key。os error 10054 或 HTTP 503。这是云浏览器集群的临时错误出现在会话更替时。Pi 会把错误反馈给模型模型通常会自动重试如果没有重新发一次提示即可。这不表示 MCP 连接有问题不要重启会话。服务器显示 0/21。这不是错误。pi-mcp-adapter 的服务器默认懒惰第一次调用 Scrapeless 工具时计数才会变成 21/21。要强制连接在/mcp里高亮服务器按CtrlR或从提示行运行/mcp reconnect scrapeless。ERR_TUNNEL_CONNECTION_FAILED。同样是云浏览器侧的临时错误重试工具调用即可。云浏览器已经通过 195 多个国家的住宅代理出口不需要你再额外配代理。要固定区域在 google_search 上用gl参数比如gl: us或gl: de。排查时记住一个原则模型通道的问题看 TaoToken 的 Base URL、Key、Model ID 三件套抓取通道的问题看 Scrapeless 的SCRAPELESS_KEY和传输方式。两条链路分开定位不要混在一起查。6. 按场景选择接入入口跑通之后根据你的使用场景选对应的入口。如果你在排查接入问题、需要重新生成或管理 API Key去 API Keys 页面和接入文档https://taotoken.net/api-keys 和 https://taotoken.net/doc 。这两个页面覆盖了 Key 创建、Base URL 说明和常见接入问题。如果你想先验证模型是否可用、对比不同模型在抓取任务上的表现用模型对话入口https://taotoken.net/models 。在这里可以直接发提示测试确认通道正常再回到 Pi 里配置。如果你打算长期用 Pi 做编码和 Agent 任务高频调用模型和工具了解 Coding Plan 会更划算https://taotoken.net/coding-plan 。它针对编码场景做了额度优化适合日常开发流。控制台入口在 https://taotoken.net/console 官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 。Claude Code 相关的接入可以参考 https://taotoken.net/claude-code 。最后分享一个实用技巧在普通使用中保持代理工具模式只把最常用的单个工具提升到directTools并保持lifecycle: lazy这样冷会话成本最低。等你发现某个工具几乎每次对话都要用再把它加进 directTools 列表。这个平衡点因工作流而异跑几天就有感觉了。