crawlgraph-mcp

crawlgraph-mcp

使用 CrawlGraph 和 Common Crawl 快照进行反向链接研究的五个 MCP 工具：backlinks、backlink_changes、gap_analysis、gap_outreach_targets 和 releases。拓展联系工具用于识别研究候选对象；它们不会发送消息或创建联系人。

选择身份验证配置

接入方式	凭据	工具配置
npm / 本地 stdio	你的 CRAWLGRAPH_API_KEY（cg_live_…）	Legacy
https://crawlgraph.com/mcp	在 Authorization: Bearer cg_live_… 中提供你的 API 密钥	Legacy
https://crawlgraph.com/mcp/connectors	在 Authorization 标头中提供与账户关联的 OAuth 访问令牌	有界目录配置（启用时）

Legacy /mcp 也接受 Smithery 的 ?apiKey=… 和 base64 JSON ?config=… 形式。凭据优先级为：标头凭据，然后是 apiKey，最后是打包的 config。建议使用 Authorization 标头。连接器端点不接受 API 密钥、查询参数凭据和打包配置；OAuth 令牌绝不会发送到公共 /api/v1 API。

目录审核和实际的 Claude/OpenAI 兼容性验证仍在进行中。我们不声称已获得 Verified 列表或徽标。本检出代码的源版本为 0.4.0；它不能证明当前的 npm 或托管版本。请分别通过 DEPLOY.md 中的运维手册验证每种分发方式。

API 密钥设置：npm / stdio 和 Legacy HTTP

通过 CrawlGraph 的 API 入门流程获取密钥。免费密钥申请流程会通过电子邮件发送密钥；它不会让你登录账户。

对于 Claude Desktop / Claude Code，请将以下内容放入客户端的 MCP 配置中：

{
  "mcpServers": {
    "crawlgraph": {
      "command": "npx",
      "args": ["-y", "crawlgraph-mcp"],
      "env": {
        "CRAWLGRAPH_API_KEY": "cg_live_your_key_here"
      }
    }
  }
}

Cursor、Windsurf、Cline 和 Zed 使用相同的命令/环境变量配置。Streamable HTTP 客户端可以使用 https://crawlgraph.com/mcp，并提供自己的 bearer API 密钥。在依赖特定来源功能前，请先确认托管服务的 tools/list 响应。

本地 stdio 设置	必需	默认值
CRAWLGRAPH_API_KEY	执行工具时必需；延迟解析	—
CRAWLGRAPH_BASE_URL	否；仅用于 Legacy REST 适配器	https://crawlgraph.com

账户关联：OAuth 连接器

当运营者启用经审核的服务后，使用现有的 CrawlGraph 账户连接到 https://crawlgraph.com/mcp/connectors，在原始连接浏览器中登录并批准授权。 创建账户不属于 OAuth 流程。如果需要账户，请按照已说明的引导流程操作， 然后返回并请求登录；仅通过电子邮件收到的 API 密钥并不代表已建立登录会话。

发行方为 https://crawlgraph.com，确切资源为 https://crawlgraph.com/mcp/connectors，唯一作用域为 crawlgraph:read。公共客户端使用授权码加 S256 PKCE，并设置 token_endpoint_auth_method=none。如果未提供注册认证方法，则会将其规范化为 none，并丢弃任何由 SDK 生成的密钥。不支持机密客户端方法和元数据文档获取。 回调必须是运营者准确批准的 HTTPS URL。OpenAI 的回调必须来自实际门户；本仓库不会提供猜测的回调。

授权和代码交换都要求使用确切的原始资源值。代码交换时，若提供了 redirect_uri，则必须与存储的回调完全一致；省略时会保留该回调。 刷新时可以省略 resource 和 scope，以保留原始授权。后端会在原子代码交换期间验证 PKCE， 并同时检查客户端、资源、重定向地址和作用域。

使用账户连接管理功能可断开连接并撤销整个授权及刷新令牌族。访问令牌过期后，只要其授权 和刷新令牌族仍有效，就可以刷新；已撤销或过期的授权则需要重新连接。发现、OAuth 和内省服务 中断时会返回 503，且不会要求重新关联。执行服务中断时，会在 HTTP 200 MCP 结果中返回安全的工具错误， 且不包含重新关联元数据。工具执行期间的撤销会通过 mcp/www_authenticate 结果元数据报告。 刷新令牌轮换没有重试宽限期：并发复用会撤销整个令牌族，而令牌响应丢失后可能需要重新连接。 在可能已提交后返回的 503 不保证授权码或刷新令牌尚未使用。

配额和目录工具

两种身份验证配置共用账户的 UTC 自然月计数器。免费账户每月有 15 次反向链接调用和 0 个差距分析任务；当前拥有付费 权限的账户每月有 1,000 次反向链接调用和 50 个差距分析任务。付费资格遵循后端当前的权限规则。 发布版本清单不消耗研究配额。backlink_changes 共用反向链接计数器。

目录输入和成本：

工具	参数	成本
backlinks	domain、limit?、sort?（authority 或 hosts）、release_id?	1 次反向链接调用
backlink_changes	domain、limit?、from_release?、to_release?	1 次反向链接调用
gap_analysis	my_domain、competitor_domains[]（1–5）、limit?、job_id?	新提交：1 个差距分析任务；轮询/恢复：0
gap_outreach_targets	差距分析输入，加上 include_platforms?、enrich_authority_top?	新提交：1 个差距分析任务；可选增加 N 次反向链接调用
releases	limit?	0

目录列表默认 20 条，最多 100 条。完整序列化的 UTF-8 CallToolResult（包括结构化数据、文本和元数据）上限为 65,536 字节。其他输出截断情况会在 crawlgraph/output 元数据中说明，并保留原始观测总数、 数据源上限、配额核算、来源信息和任务句柄。大型导出应通过账户/API 界面进行。 Gap 工具在 90 秒的工具预算内最多轮询 75 秒。待处理结果包含 job_id 和规范化后的请求。使用该句柄和查询恢复同一个工具；重新连接后，同一所有者可使用新的有效授权恢复。轮询不消耗 gap 任务。超时、取消、网络中断或工作进程过期后，绝不自动提交替代请求：已接受的任务仍可能完成。取消会停止后续轮询。已接受的提交仍会计费；响应丢失或格式错误时，应报告消耗量未知，而不是声称为零。

Node 会向 stderr 写入有界 JSON 遥测数据。每次目录工具调用都会记录内部生成的关联 ID、固定工具名称（或 unknown）、最终信封状态、isError、允许列表中的主要和部分错误代码、延迟，以及最终序列化 UTF-8 结果的确切大小（不含传输帧）。已知的计费调用次数和消耗量未知的类别取自最终信封。待处理任务的取消，以及带有部分撤销信息的已完成结果，均保留各自不同的状态和错误字段。HTTP/OAuth 错误只记录固定的路由类别、状态、允许列表中的代码，以及单独的响应本地关联 ID。日志记录失败不会改变响应。日志不包含参数、域名、结果、任务／账户／授权／客户端／来源 ID、调用方请求 ID、异常文本、URL、标头、配置或凭据。

OAuth 来源准入仅在本地桶键中按 /64 对 IPv6 地址分组。映射的 IPv4 地址与其 IPv4 形式使用同一个桶。私有 RPC 仍会收到完整的规范化、已验证入口来源。达到容量时，有界桶映射会采取默认拒绝策略，不会逐出仍有效的时间窗口；后端仍会执行自身的策略。

推广功能会保留后端按竞争对手重叠度、权威性和域名进行的排名。平台筛选计数仅描述后端返回的样本。丰富数据默认值为 0；明确请求 enrich_authority_top=N（0–5），即可对保留的目标最多额外调用 N 次反向链接工具。发生部分失败时，会保留已完成的结果、各项来源信息、实际已知费用、最近观察到的配额以及任何未知消耗量。已验证任务使用其经过认证的版本进行丰富数据处理；旧版任务则保留 null 来源信息，并记录单独的查询版本。

旧版工具保留原有字段和默认值：反向链接工具在公共 API 上默认返回 1,000 行，最多 10,000 行；推广工具使用 enrich_top，默认值为 10，最大值为 25，每次丰富数据调用一次反向链接工具。旧版 gap 工具会在现有的 90 秒窗口内提交并轮询，且没有目录 job_id 输入。估算配额用量前，请先检查所选配置文件。

解读结果

Common Crawl 是定期观测数据，并非实时链接监控。标注的版本来源信息不能证明某个页面当前仍链接到某个目标。引用域名已移除，表示它未出现在较新的快照中，而非已证实其在线删除。无法进行比较与变化为零不同；总数未知和受来源上限限制的下限与完整的空结果不同。Gap 来源信息会在执行时保存，并在后续轮询中保留。较旧且未经认证的产物会报告 legacy_unverified，版本标识为 null。引用域名重叠表示可作为研究对象，但不代表发布方从未听说过你。

示例研究提示词：

查找 mine.example 相对于 a.example 和 b.example 的反向链接缺口。如果任务仍在等待处理，请恢复返回的任务，不要重新提交。提出任何可选的权威性丰富数据建议前，先报告来源信息、上限和配额用量。

开发与验证

npm install
npm run build
node --test tests/*.test.mjs

构建过程也会进行 TypeScript 检查；未配置单独的 lint 脚本。 测试使用已安装的 SDK、本地 HTTP 测试替身和模拟的私有／公开后端回复。测试需要获得绑定环回地址套接字的权限，但不需要生产凭据或访问实时提供商。Node 测试替身无法验证后端的 SQLite 事务、配额隔离或查询固定；这些由单独的 crawlback 后端 HTTP 测试和完整发布门禁覆盖。

实现参考：HTTP 接口、 OAuth 路由器、提供商、 私有后端客户端、 目录工具和旧版服务。

许可证

MIT