简体中文

English

简体中文

English

Claude Code + XCrawl MCP 使用指南

本文档介绍如何在 Claude Code 中集成 XCrawl MCP Server，让 Claude Code 直接获得网页抓取、搜索、URL 发现和批量爬取能力。

前置准备

获取 XCrawl API Key

  1. 前往 dash.xcrawl.com 注册账号
  2. 注册后免费获得 1000 积分
  3. 在 dash.xcrawl.com/api-key 获取 API Key

环境要求

  • 已安装 Claude Code
  • 如使用本地 npx 方式：Node.js >= 18
  • 如使用云端 URL 方式：无额外依赖

方式一：云端托管 URL

推荐使用该方式，无需本地依赖，即配即用。

claude mcp add --transport http xcrawl https://mcp.xcrawl.com/{YOUR_API_KEY}/mcp

按作用域添加：

# 全局可用
claude mcp add --scope user --transport http xcrawl https://mcp.xcrawl.com/{YOUR_API_KEY}/mcp

# 当前项目，写入 .mcp.json，可提交 git
claude mcp add --scope project --transport http xcrawl https://mcp.xcrawl.com/{YOUR_API_KEY}/mcp

方式二：本地 npx 方式

适合离线或内网环境，也适合需要自定义控制的场景。

claude mcp add xcrawl -e XCRAWL_API_KEY={YOUR_API_KEY} -- npx -y xcrawl-mcp

方式三：项目级配置文件

在项目根目录创建 .mcp.json：

{
  "mcpServers": {
    "xcrawl": {
      "type": "http",
      "url": "https://mcp.xcrawl.com/{YOUR_API_KEY}/mcp"
    }
  }
}

或使用 npx 本地方式，配合环境变量避免泄露 Key：

{
  "mcpServers": {
    "xcrawl": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "xcrawl-mcp"],
      "env": {
        "XCRAWL_API_KEY": "${XCRAWL_API_KEY}"
      }
    }
  }
}

注

.mcp.json 支持 ${VAR} 和 ${VAR:-default} 环境变量展开语法，避免将 API Key 硬编码提交到 git。

方式四：Claude Desktop

如需在 Claude Desktop 而非 Claude Code CLI 中使用：

配置文件路径：

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

HTTP 方式：

{
  "mcpServers": {
    "xcrawl": {
      "url": "https://mcp.xcrawl.com/{YOUR_API_KEY}/mcp"
    }
  }
}

注

如当前 Claude Desktop 版本不支持 HTTP，可改用 npx 方式。

npx 方式：

{
  "mcpServers": {
    "xcrawl": {
      "command": "npx",
      "args": ["-y", "xcrawl-mcp"],
      "env": {
        "XCRAWL_API_KEY": "{YOUR_API_KEY}"
      }
    }
  }
}

验证配置

# 列出已配置的 MCP 服务器
claude mcp list

# 查看 xcrawl 详细配置
claude mcp get xcrawl

在 Claude Code 会话中输入 /mcp 查看连接状态和可用工具。

管理命令

claude mcp list             # 列出所有 MCP 服务器
claude mcp get xcrawl       # 查看 xcrawl 配置详情
claude mcp remove xcrawl    # 移除 xcrawl

可用工具

配置完成后，Claude Code 可使用以下 7 个 XCrawl 工具：

工具用途
xcrawl_scrape单页抓取，支持 markdown/html/json/截图输出
xcrawl_searchGoogle 搜索引擎，支持地区/语言/高级 SERP 参数
xcrawl_map站点 URL 发现，支持正则过滤、子域名
xcrawl_crawl批量爬取，支持深度和路径控制
xcrawl_key_status查询 API Key 有效性和积分余额
xcrawl_check_status查询异步抓取任务状态
xcrawl_check_crawl_status查询异步批量爬取任务状态

使用示例

# 单页抓取
使用 xcrawl_scrape 抓取 https://example.com，同步模式，返回 markdown 和链接

# 搜索
使用 xcrawl_search 搜索 "Claude Code MCP"，美国英文，返回前 10 条

# URL 发现
使用 xcrawl_map 列出 https://docs.xcrawl.com 下 /doc/ 路径的 URL，上限 2000

# 批量爬取
使用 xcrawl_crawl 从 https://docs.xcrawl.com/doc/ 开始爬取，最大深度 2，上限 100 页，完成后轮询结果

常见问题

问题解决方案
服务器连接超时设置 MCP_TIMEOUT=30000 延长超时
spawn npx ENOENT安装 Node.js LTS，确保 npx 在 PATH 中
HTTP 方式连接失败可能客户端版本不支持，改用 npx 方式
工具不显示运行 /mcp 检查服务器状态和连接
输出被截断设置 MAX_MCP_OUTPUT_TOKENS=50000
401 UnauthorizedAPI Key 无效，在 dash.xcrawl.com 重新获取
积分不足调用 xcrawl_key_status 检查，升级套餐
健康检查curl https://mcp.xcrawl.com/health 应返回 OK