在 Claude Code 里真正用起来 CrawlForge MCP

你装好了 CrawlForge MCP。Claude Code 显示已连接。然后你让它取一个页面，它却凭记忆给你总结，或者转头去用内置的抓取工具，又或者在做成任何有用的事之前先问你四遍权限。

这不是装坏了。这是 MCP tools 调用方式上的一个断层，用大约五分钟的配置就能补上。

claude mcp list
# crawlforge: npx -y crawlforge-mcp-server - ✔ Connected

本文讲的是安装之后的事：Claude 如何决定调用一个工具、如何让它优先选择 CrawlForge 而不是内置的网页工具、如何终结权限提示，以及如何用最少的 credits 挑到能干成活的那个工具。

目录

• 为什么 Claude 会忽略你的 MCP server
• 工具调用实际是怎么发生的
• 第 1 步：确认服务器已连接
• 第 2 步：需要时直接点名工具
• 第 3 步：把 CrawlForge 策略写进 CLAUDE.md
• 第 4 步：终结权限提示
• 选对工具
• 保护你的上下文窗口
• 真正有效的提示词模式
• 把配置分享给团队
• 在脚本和 CI 中以 headless 方式运行
• 故障排查

为什么 Claude 会忽略你的 MCP server

这里其实有三种互不相同的失败，各自需要不同的解法。

Claude 还不知道这些工具存在。 Claude Code 默认启用工具搜索。会话启动时它只加载工具的名称和服务器自身的说明，完整的工具定义会一直推迟到某个任务真正需要时才载入。这样能让你的上下文窗口保持空闲，但也意味着「我没看到列出 31 个工具」是正常现象，而不是哪里出了毛病。

Claude 手上有个看起来差不多的内置工具。 Claude Code 自带 WebFetch 和 WebSearch。你要「这个页面的内容」，一个讲道理的模型完全可能顺手用内置的，而不是去搜索一个还得先发现的 MCP tool。这不是坏了，只是你没告诉它你更想用哪个。

调用确实发生了，但每一次都要批准。 在你放行之前，每次 MCP tool 调用都会弹出权限提示。一个研究任务里被打断四次，感觉就像这套集成在跟你作对。

本文剩下的部分把这三件事都解决掉。

工具调用实际是怎么发生的

你并不去调用一个 MCP tool。你描述想要的结果，由 Claude 挑工具，就跟它在 Read 和 Grep 之间做选择一样。

每个 MCP tool 都有一个规范名称，形式是 mcp__<server>__<tool>。CrawlForge 注册为 crawlforge 时，它的工具就是：

mcp__crawlforge__scrape
mcp__crawlforge__search_web
mcp__crawlforge__deep_research
mcp__crawlforge__stealth_mode

平时你不会去敲这些名字。它们在两个地方有用：权限规则按规范名称匹配；以及当 Claude 挑错工具时，你可以用点名的方式兜底。

第 1 步：确认服务器已连接

在调提示词之前，先确认传输层是通的。在你的 shell 里：

claude mcp list

每个服务器都会有一个健康状态。你实际会遇到的是这四种：

在会话内部，/mcp 打开同一个视图，并带有按服务器划分的详情面板；服务器失败时其中会有一行 Issue:。

有个细节值得知道：配置一旦写入，claude mcp add 就会打印 Added ...，它并不做任何校验。API key 打错了照样会打印成功那一行。真正管用的检查是 claude mcp list。

第 2 步：需要时直接点名工具

当 Claude 挑错工具——或者一个都不挑——的时候，直接说你要哪个。下面两种写法都有效：

Use scrape to get https://example.com/pricing as markdown.

Use mcp__crawlforge__deep_research to compare the three vendors on
that page, then write the findings to research.md.

实践中光写工具名就够了。当某个名称在多个服务器之间有歧义，或者你在写一个必须毫不含糊的 slash command 或脚本时，再用完整的 mcp__crawlforge__* 形式。

点名工具是个不错的排查手段，却是个坏习惯。如果你发现自己每条提示词都要这么写，那就去修默认行为——这正是下一步。

第 3 步：把 CrawlForge 策略写进 CLAUDE.md

这是整篇文章里收益最高的一处改动。CLAUDE.md 每次会话都会载入上下文，所以一小段策略就能永久改变 Claude 会去拿哪个工具：

# Web Access Policy

Use CrawlForge MCP tools for all web search and page fetching.

- Web search: `search_web` (not the built-in WebSearch)
- Single page: `scrape` with `formats: ["markdown"]`
- Article text only: `extract_content`
- Site structure: `map_site`, then `crawl_deep` if you need page bodies
- Multi-source research: `deep_research`
- JS-rendered or anti-bot pages: `scrape_with_actions` or `stealth_mode`

Prefer one `batch_scrape` call over a loop of single fetches.

把它放进项目的 CLAUDE.md，或者放进 ~/.claude/CLAUDE.md 让它处处生效。两次会话之后你就会忘了还有这么个东西——这正是它的意义所在。

把偏好平实地说一遍就行。一段每行都在吼 ALWAYS 和 NEVER 的文字，往往会让模型矫枉过正，在根本不需要抓取的问题上也去掏抓取工具。

第 4 步：终结权限提示

加一条放行规则，让 CrawlForge 的工具不受打断地跑起来。在 .claude/settings.json 里：

{
  "permissions": {
    "allow": [
      "mcp__crawlforge__*"
    ]
  }
}

模式规则，直接来自权限参考文档：

• mcp__crawlforge — 该服务器的所有工具
• mcp__crawlforge__* — 同上，通配符写法
• mcp__crawlforge__scrape — 仅这一个工具
• mcp__crawlforge__extract_* — 四个抽取类工具

放行规则必须锚定到一个字面的服务器前缀。光写 "mcp__*" 会被跳过并给出警告，什么都不会自动放行，因为它没有指明任何你实际配置过的服务器。

如果你更想放行便宜的工具、对贵的那些留一手，那就放行读取类，其余继续保持提示：

{
  "permissions": {
    "allow": [
      "mcp__crawlforge__scrape",
      "mcp__crawlforge__extract_content",
      "mcp__crawlforge__search_web",
      "mcp__crawlforge__map_site"
    ]
  }
}

这样 10 credits 的 deep_research 和 8 credits 的 agent 仍然会先问一句。

选对工具

二十七个工具是相当大的一片面上，而 Claude 会心安理得地在 1 个 credit 够用的地方花掉 5 个。成本如下：

三条规则覆盖了绝大多数情况：

逐级往上，别一上来就顶格。 先试 fetch_url（1）或 scrape（2）。只有当内容是客户端渲染时才升级到 scrape_with_actions（5），只有真的被拦了才用 stealth_mode（5）。相当多看着有防护的站点，对一个格式规范的请求其实照给不误。

用批量，别用循环。 一次 batch_scrape 调用不管传多少个 URL 都是 5 credits。十二次单独的 scrape 就是 24 credits 外加十二个来回。说一句「把这些放在一个批次里抓」，差距是实打实的。

清楚 deep_research 替代的是什么。 10 credits 让它成为最贵的工具，而当它顶掉的是一次搜索加八次抓取再加一轮综合时，这很划算。当你已经知道 URL 时，它就是浪费。有链接就直接抓。

保护你的上下文窗口

这是没人提醒过你的那种失败：一次成功的抓取毁掉了整个会话。网页很大，而 MCP 的结果是直接落进对话里的。

Claude Code 有护栏。任何 MCP tool 的输出超过 10,000 tokens 时它会警告，默认把输出上限压在 25,000 tokens。你可以抬高这个天花板：

export MAX_MCP_OUTPUT_TOKENS=50000

抬高它通常是错误的直觉。有三个更好的做法：

要你需要的那个形态。 scrape 默认返回 markdown，并通过 Readability 剥掉导航、广告和页脚。在现代站点上要 rawHtml，token 量可能翻十倍却毫无收益。

把大批量输出导到磁盘。 凡是你打算处理而不是阅读的内容，让 Claude 写出去：

Batch scrape these 20 URLs and write each result to data/<domain>.md.
Then give me a one-line summary of each — do not paste the bodies.

Claude 在上下文里留下的是 30 行摘要，而不是 20 篇文章。

用便宜的工具做分诊。 extract_metadata（1 credit）用几百个 token 就能回答「这页值不值得读」。map_site（2）给你一份 URL 清单，一个正文都不用取。先摸清全貌，再去取真正要紧的。

真正有效的提示词模式

含糊的请求和具体的请求之间，差的通常就是多写两句。

指明输出的形态。

把那个页面的定价给我。

抓取 https://example.com/pricing 并返回 JSON： [{ plan, monthly_price, annual_price, included_credits }]。 没有列出的字段用 null。

说清楚数据要拿去干什么。 Claude 默认会把结果打印出来。如果你要的是一个文件、一份 diff 或者一个测试，就直说：

Search for the top 10 results on "MCP web scraping", scrape each one,
and write a comparison table to docs/competitors.md. Skip anything
that 403s and note it at the bottom.

提前把升级路径给它。 这能省下一整个来回：

Scrape https://app.example.com/dashboard. If the content looks
client-rendered, retry with scrape_with_actions waiting on
.data-grid. If you get a 403, use stealth_mode.

接到 Claude Code 本来就擅长的活儿上。 在你的终端里做抓取，真正的好处是数据落在了你的代码旁边：

Scrape the Stripe webhook events reference, then check
src/lib/stripe/webhooks.ts for event types we handle that
no longer appear in their docs.

这是一条提示词同时覆盖了一次抓取、一次仓库读取和一次比对——这三样没有哪一样是浏览器标签页能替你做的。

把配置分享给团队

MCP servers 有三种安装作用域。默认是 local：只属于你，只在当前项目内，存放在 ~/.claude.json。

给团队用的话，用 project 作用域，它会在仓库根目录写入 .mcp.json：

claude mcp add crawlforge \
  --scope project \
  --env CRAWLFORGE_API_KEY=cf_live_your_key_here \
  -- npx -y crawlforge-mcp-server

别把带着真实密钥的那个文件提交上去。.mcp.json 支持环境变量展开，所以提交引用就好：

{
  "mcpServers": {
    "crawlforge": {
      "command": "npx",
      "args": ["-y", "crawlforge-mcp-server"],
      "env": {
        "CRAWLFORGE_API_KEY": "${CRAWLFORGE_API_KEY}"
      }
    }
  }
}

这样每个开发者克隆下来就有了服务器，各自从自己的 shell 提供密钥。${VAR:-default} 的写法同样可用，展开适用于 command、args、env、url 和 headers。

用项目作用域有两件事要有预期。Claude Code 会要求每个开发者在首次使用时批准该服务器——这是刻意为之，否则一个仓库就能夹带一个克隆即运行的服务器。另外，如果变量未设置又没有默认值，配置照样会加载：claude mcp list 会报一个变量缺失的警告，并把字面量 ${CRAWLFORGE_API_KEY} 原样传下去，这在之后会表现为 401。

如果某个服务器你希望在这台机器的所有项目里都有，就用 user 作用域（--scope user）。

在脚本和 CI 中以 headless 方式运行

上面所有内容在非交互模式下都成立，只有一点不同：没有人来回答提示，所以权限必须提前定好。

claude -p "Scrape https://news.ycombinator.com and write the top 10 \
stories as JSON to hn.json" \
  --allowedTools "mcp__crawlforge__scrape,Write"

来自 .mcp.json 的项目级服务器在 claude -p 中会直接加载，不走批准提示——因为那个提示根本没法显示。这让提交进版本库的 .mcp.json 成了 CI 的自然选择。如果你需要把某个服务器挡在自动化运行之外，disabledMcpjsonServers 在所有模式下都能拦住它。

于是一个每日监控就是一个 cron job 加一条提示词：

claude -p "Use track_changes on https://competitor.com/pricing. \
If anything changed since the last run, append it to CHANGES.md." \
  --allowedTools "mcp__crawlforge__track_changes,Read,Write"

故障排查

✘ Failed to connect — 运行 claude mcp get crawlforge 并读那行 Issue:，它带着 HTTP 状态码或错误文本。对于 stdio 服务器，先确认 npx -y crawlforge-mcp-server 单独能跑起来。

所有工具都返回 401 — API key 不对，或者带了看不见的空白字符。粘贴密钥经常会捎上一个结尾换行；Claude Code 会在 claude mcp list 和 /mcp 里用一条点名字段的警告标出来。重新添加服务器，并确认密钥以 cf_live_ 开头。

⏸ Pending approval — 项目级服务器需要交互式批准。在该目录下运行 claude 并接受。在刚克隆的仓库里，你还得先接受 workspace 信任对话框——仓库不能批准它自己的服务器。claude mcp reset-project-choices 可以清除之前的选择。

Claude 还是在用 WebFetch — 回到第 3 步。在没有声明偏好的情况下，用内置的是个说得过去的选择。

工具输出被截断 — 你撞上了 25,000 tokens 的上限。与其抬高 MAX_MCP_OUTPUT_TOKENS，不如把请求收窄；参见保护你的上下文窗口。

credits 不足 — 去用量面板看看。Free 账户获得 1,000 个一次性 credits；Hobby 是每月 19 USD 换 5,000。

页面在浏览器里能打开，抓下来却是空的 — 客户端渲染。改用 scrape_with_actions 重试，并等待一个只有水合之后才存在的选择器。

下一步

• 刚开始配置？先看安装指南
• 专讲抓取的实操：如何用 Claude Code 抓取网站
• 协议背景：面向开发者的 MCP 协议详解
• 完整工具参考：快速上手文档

在 crawlforge.dev/signup 用 1,000 credits 免费开始。无需信用卡。