ScrapeGraphAI-scrapegraph-mcp

ScrapeGraph MCP Server

一个可用于生产环境的 Model Context Protocol（MCP）服务，可与 ScrapeGraph AI API 无缝集成。此服务让大模型能够利用先进的 AI 驱动网页抓取功能，并具备企业级可靠性。

目录

• 主要功能
• 快速开始
• 可用工具
• 设置说明
• 远程服务用法
• 本地用法
• Google ADK 集成
• 示例用例
• 错误处理
• 常见问题
• 开发
• 贡献
• 文档
• 技术栈
• 许可证

API v2

此 MCP 服务面向 ScrapeGraph API v2（https://v2-api.scrapegraphai.com/api），与 scrapegraph-py PR #84 保持 1:1 一致。身份验证使用 SGAI-APIKEY 请求头。环境变量与 Python SDK 保持一致：

• SGAI_API_URL — 覆盖基础 URL（默认值为 https://v2-api.scrapegraphai.com/api）
• SGAI_TIMEOUT — 请求超时时间，单位为秒（默认值为 120）
• SGAI_API_KEY — API 密钥（也可通过 MCP scrapegraphApiKey 或 X-API-Key 请求头传入）

旧版别名（仍受支持）：SGAI_API_URL 对应 SCRAPEGRAPH_API_BASE_URL，SGAI_TIMEOUT 对应 SGAI_TIMEOUT_S。

主要功能

• 抓取与提取：scrape（POST /scrape，多种格式）、extract（POST /extract，URL + 提示词）
• 搜索：search（POST /search；num_results 限制在 3–20）
• 爬取：异步多页面爬取，支持 crawl_start / crawl_get_status / crawl_stop / crawl_resume
• 架构：schema（POST /schema）——根据提示词生成或扩展 JSON Schema
• 监控：通过 monitor_create、monitor_list、monitor_get 创建计划任务，支持暂停、恢复、删除，以及 monitor_activity（分页查看运行历史）
• 账户：credits、history
• 轻松集成：Claude Desktop、Cursor、Smithery、HTTP 传输
• 开发者文档：.agent/ 文件夹

迁移：v2 → v3

v3 重命名了所有与 v2 API 文档不一致的 MCP 工具。直接重命名，不提供别名。

v2（旧）	v3（新）
smartscraper	extract
searchscraper	search
smartcrawler_initiate	crawl_start
smartcrawler_fetch_results	crawl_get_status
sgai_history	history
generate_schema	schema
markdownify	已移除 — 使用 scrape 并设置 output_format="markdown"

快速开始

1. 获取 API 密钥

注册并从 ScrapeGraph Dashboard 获取 API 密钥。

2. 使用 Smithery 安装（推荐）

npx -y @smithery/cli install @ScrapeGraphAI/scrapegraph-mcp --client claude

3. 开始使用

向 Claude 或 Cursor 提问：

• “将 https://scrapegraphai.com 转换为 Markdown”
• “从这个电商页面提取所有商品价格”
• “研究 AI 领域的最新进展并总结发现”

就是这么简单！现在，AI 助手即可使用此服务。

可用工具

工具	作用
scrape	POST /scrape（output_format：markdown、html、screenshot、branding、links、images、summary）
extract	POST /extract（需要 website_url + user_prompt；可选 output_schema）
search	POST /search（num_results 为 1–20；支持 country_search、time_range、output_schema）
crawl_start	POST /crawl — extraction_mode：markdown / html / links / images / summary / branding / screenshot
crawl_get_status	GET /crawl/:id（轮询，直到 status: completed）
crawl_stop、crawl_resume	POST /crawl/:id/stop | resume
schema	POST /schema（根据提示词生成或扩展 JSON Schema）
credits	GET /credits
history	GET /history（分页，service 筛选条件）
monitor_create、monitor_list、monitor_get、monitor_pause、monitor_resume、monitor_delete	/monitor API
monitor_activity	GET /monitor/:id/activity（分页的轮询历史：id、createdAt、status、changed、elapsedMs、diffs）

已移除： sitemap、agentic_scrapper、异步状态轮询，以及（在 v3 中）markdownify——请使用 scrape 并设置 output_format="markdown"。

设置说明

要使用此服务，您需要一个 ScrapeGraph API 密钥。请按照以下步骤获取：

1. 前往 ScrapeGraph 控制台
2. 创建账户并生成 API 密钥

通过 Smithery 自动安装

通过 Smithery 自动安装 ScrapeGraph API 集成服务：

npx -y @smithery/cli install @ScrapeGraphAI/scrapegraph-mcp --client claude

Claude Desktop 配置

使用以下设置更新 Claude Desktop 配置文件（位于 Cursor 页面右上方）：

（请记得在配置中添加您的 API 密钥）

{
    "mcpServers": {
        "@ScrapeGraphAI-scrapegraph-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@smithery/cli@latest",
                "run",
                "@ScrapeGraphAI/scrapegraph-mcp",
                "--config",
                "\"{\\\"scrapegraphApiKey\\\":\\\"YOUR-SGAI-API-KEY\\\"}\""
            ]
        }
    }
}

配置文件位于：

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

Cursor 集成

在设置中添加 ScrapeGraphAI MCP 服务：

远程服务用法

连接到我们托管的 MCP 服务——无需本地安装！

警告

旧版 MCP 端点 https://mcp.scrapegraphai.com/mcp 即将弃用。 新集成应使用替代 MCP 端点： https://sgai-mcp-main.onrender.com。

Claude Desktop 配置（远程）

将以下内容添加到 Claude Desktop 配置文件中（macOS 上的路径为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "scrapegraph-mcp": {
      "command": "npx",
      "args": [
        "[email protected]",
        "https://sgai-mcp-main.onrender.com",
        "--header",
        "X-API-Key:YOUR_API_KEY"
      ]
    }
  }
}

Cursor 配置（远程）

Cursor 原生支持 HTTP MCP 连接。请将以下内容添加到 Cursor MCP 设置（~/.cursor/mcp.json）：

{
  "mcpServers": {
    "scrapegraph-mcp": {
      "url": "https://sgai-mcp-main.onrender.com",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

远程服务的优势

• 无需本地设置——配置后即可开始使用
• 始终保持最新——自动获取最新更新
• 跨平台——可在任何安装了 Node.js 的操作系统上运行

本地用法

要在本地运行 MCP 服务进行开发或测试，请按照以下步骤操作：

先决条件

• Python 3.13 或更高版本
• pip 或 uv 包管理器
• ScrapeGraph API 密钥

安装

1. 克隆仓库（如果尚未克隆）：

git clone https://github.com/ScrapeGraphAI/scrapegraph-mcp
cd scrapegraph-mcp

2. 安装软件包：

# Using pip
pip install -e .

# Or using uv (faster)
uv pip install -e .

3. 设置您的 API 密钥：

# macOS/Linux
export SGAI_API_KEY=your-api-key-here

# Windows (PowerShell)
$env:SGAI_API_KEY="your-api-key-here"

# Windows (CMD)
set SGAI_API_KEY=your-api-key-here

在本地运行服务

您可以直接运行服务：

# Using the installed command
scrapegraph-mcp

# Or using Python module
python -m scrapegraph_mcp.server

服务将启动并通过 stdio（标准输入/输出）进行通信，这是标准的 MCP 传输方式。

使用 MCP Inspector 进行测试

使用 MCP Inspector 工具测试您的本地服务：

npx @modelcontextprotocol/inspector python -m scrapegraph_mcp.server

这将提供一个 Web 界面，让您以交互方式测试所有可用工具。

配置 Claude Desktop 以使用本地服务

要通过 Claude Desktop 使用本地运行的服务，请更新配置文件：

macOS/Linux（~/Library/Application Support/Claude/claude_desktop_config.json）：

{
    "mcpServers": {
        "scrapegraph-mcp-local": {
            "command": "python",
            "args": [
                "-m",
                "scrapegraph_mcp.server"
            ],
            "env": {
                "SGAI_API_KEY": "your-api-key-here"
            }
        }
    }
}

Windows（%APPDATA%\Claude\claude_desktop_config.json）：

{
    "mcpServers": {
        "scrapegraph-mcp-local": {
            "command": "python",
            "args": [
                "-m",
                "scrapegraph_mcp.server"
            ],
            "env": {
                "SGAI_API_KEY": "your-api-key-here"
            }
        }
    }
}

注意：确保 Python 位于 PATH 中。你可以在终端中运行 python --version 进行验证。

配置 Cursor 以使用本地服务

在 Cursor 的 MCP 设置中，添加一个新服务并填写：

• 命令：python
• 参数：["-m", "scrapegraph_mcp.server"]
• 环境变量：{"SGAI_API_KEY": "your-api-key-here"}

本地设置故障排除

服务无法启动：

• 验证是否已安装 Python：python --version
• 检查是否已安装该软件包：pip list | grep scrapegraph-mcp
• 确保已设置 API 密钥：echo $SGAI_API_KEY（macOS/Linux）或 echo %SGAI_API_KEY%（Windows）

未显示工具：

• 查看 Claude Desktop 日志：
  • macOS：~/Library/Logs/Claude/
  • Windows：%APPDATA%\Claude\Logs\
• 验证直接运行时服务能否正常启动
• 检查配置 JSON 是否有效

导入错误：

• 重新安装软件包：pip install -e . --force-reinstall
• 验证依赖项：pip install -r requirements.txt（如果有）

Google ADK 集成

ScrapeGraph MCP 服务可以与 Google ADK（Agent Development Kit） 集成，以创建具备网页抓取能力的 AI Agent。

前提条件

• Python 3.13 或更高版本
• 已安装 Google ADK
• ScrapeGraph API 密钥

安装

1. 安装 Google ADK（如果尚未安装）：

pip install google-adk

2. 设置 API 密钥：

export SGAI_API_KEY=your-api-key-here

基本集成示例

创建一个 Agent 文件（例如 agent.py），并使用以下配置：

import os
from google.adk.agents import LlmAgent
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StdioConnectionParams
from mcp import StdioServerParameters

# Path to the scrapegraph-mcp server directory
SCRAPEGRAPH_MCP_PATH = "/path/to/scrapegraph-mcp"

# Path to the server.py file
SERVER_SCRIPT_PATH = os.path.join(
    SCRAPEGRAPH_MCP_PATH, 
    "src", 
    "scrapegraph_mcp", 
    "server.py"
)

root_agent = LlmAgent(
    model='gemini-2.0-flash',
    name='scrapegraph_assistant_agent',
    instruction='Help the user with web scraping and data extraction using ScrapeGraph AI. '
                'You can convert webpages to markdown, extract structured data using AI, '
                'perform web searches, crawl multiple pages, and automate complex scraping workflows.',
    tools=[
        MCPToolset(
            connection_params=StdioConnectionParams(
                server_params=StdioServerParameters(
                    command='python3',
                    args=[
                        SERVER_SCRIPT_PATH,
                    ],
                    env={
                        'SGAI_API_KEY': os.getenv('SGAI_API_KEY'),
                    },
                ),
                timeout=300.0,)
            ),
            # Optional: Filter which tools from the MCP server are exposed
            # tool_filter=['scrape', 'extract', 'search']
        )
    ],
)

配置选项

超时设置：

• 默认超时时间为 5 秒，对于网页抓取操作而言可能太短
• 建议：设置 `timeout=300.0
• 根据你的使用场景进行调整（爬取操作可能需要更长的超时时间）

工具筛选：

• 默认情况下，所有已注册的 MCP 工具都会提供给 Agent（参见可用工具）
• 使用 tool_filter 限制可用工具：

  tool_filter=['scrape', 'extract', 'search']
  

API 密钥配置：

• 通过环境变量设置：export SGAI_API_KEY=your-key
• 或直接在 env 字典中传入：'SGAI_API_KEY': 'your-key-here'
• 出于安全考虑，建议使用环境变量

使用示例

配置完成后，你的 Agent 可以使用自然语言与网页抓取工具交互：

# The agent can now handle queries like:
# - "Convert https://example.com to markdown"
# - "Extract all product prices from this e-commerce page"
# - "Search for recent AI research papers and summarize them"
# - "Crawl this documentation site and extract all API endpoints"

如需了解更多 Google ADK 信息，请访问官方文档。

示例用例

该服务支持针对各种抓取场景执行复杂查询：

单页抓取

• Markdownify：“将 ScrapeGraph 文档页面转换为 Markdown”
• 提取：“从此电商页面中提取所有产品名称、价格和评分”
• 滚动提取：“抓取此无限滚动页面，滚动 5 次并提取所有项目”
• 基础抓取：“使用完整渲染功能获取此 JavaScript 密集型页面的 HTML 内容”

搜索与研究

• 搜索：“研究并总结 AI 驱动的网页抓取领域近期进展”
• 搜索：“搜索机器学习框架相关的 5 篇热门文章，并提取关键见解”
• 搜索：“查找 GPT-4 的近期新闻并提供结构化摘要”
• 搜索：v2 不支持 time_range；请在自然语言查询中调整措辞，以便偏向近期内容

网站分析

• 使用 crawl_start 加上 crawl_get_status 映射并捕获多页内容；v2 没有单独的 sitemap 工具。

多页爬取

• 爬取：“以 Markdown 模式爬取该博客，并持续轮询直到完成”
• 如需提取每页的结构化字段，可对单个 URL 运行 extract（或按计划运行 monitor_create）

监控和账户

• 监控：「每天上午 9 点在 https://example.com 上运行此提取提示词」（使用带间隔的 monitor_create）
• 积分 / 历史记录：credits、history
• Agentic Scraper：「执行复杂工作流：登录、导航到报告页面、下载数据并提取汇总统计信息」

错误处理

该服务实现了完善的错误处理机制，并针对以下问题提供详细且可操作的错误消息：

• API 身份验证问题
• URL 结构格式错误
• 网络连接故障
• 速率限制和配额管理

常见问题

Windows 特定连接

在 Windows 系统上运行时，可能需要使用以下命令连接到 MCP 服务：

C:\Windows\System32\cmd.exe /c npx -y @smithery/cli@latest run @ScrapeGraphAI/scrapegraph-mcp --config "{\"scrapegraphApiKey\":\"YOUR-SGAI-API-KEY\"}"

这可确保在 Windows 环境中正确执行。

其他常见问题

“ScrapeGraph 客户端未初始化”

• 原因：缺少 API 密钥
• 解决方案：设置 SGAI_API_KEY 环境变量，或通过 --config 提供

“Error 401: Unauthorized”

• 原因：API 密钥无效
• 解决方案：在 ScrapeGraph Dashboard 验证 API 密钥

“Error 402: Payment Required”

• 原因：积分不足
• 解决方案：为 ScrapeGraph 账户充值

爬取未返回结果

• 原因：仍在处理中（异步操作）
• 解决方案：持续轮询 crawl_get_status()，直到状态为 "completed"

Claude Desktop 中未显示工具

• 原因：服务未启动或配置错误
• 解决方案：检查 Claude 日志：~/Library/Logs/Claude/（macOS）或 %APPDATA%\Claude\Logs\（Windows）

如需详细的故障排查信息，请参阅 .agent 文档。

开发

前置条件

• Python 3.13 或更高版本
• pip 或 uv 包管理器
• ScrapeGraph API 密钥

从源代码安装

# Clone the repository
git clone https://github.com/ScrapeGraphAI/scrapegraph-mcp
cd scrapegraph-mcp

# Install dependencies
pip install -e ".[dev]"

# Set your API key
export SGAI_API_KEY=your-api-key

# Run the server
scrapegraph-mcp
# or
python -m scrapegraph_mcp.server

使用 MCP Inspector 测试

使用 MCP Inspector 工具在本地测试服务：

npx @modelcontextprotocol/inspector scrapegraph-mcp

这会提供一个 Web 界面，用于测试所有可用工具。

代码质量

Lint 检查：

ruff check src/

类型检查：

mypy src/

格式检查：

ruff format --check src/

项目结构

scrapegraph-mcp/
├── src/
│   └── scrapegraph_mcp/
│       ├── __init__.py      # Package initialization
│       └── server.py        # Main MCP server (all code in one file)
├── .agent/                  # Developer documentation
│   ├── README.md           # Documentation index
│   └── system/             # System architecture docs
├── assets/                  # Images and badges
├── pyproject.toml          # Project metadata & dependencies
├── smithery.yaml           # Smithery deployment config
└── README.md               # This file

参与贡献

欢迎贡献！以下是你可以提供帮助的方式：

添加新工具

1. 在 server.py 中向 ScapeGraphClient 类添加方法：

def new_tool(self, param: str) -> Dict[str, Any]:
    """Tool description."""
    url = f"{self.BASE_URL}/new-endpoint"
    data = {"param": param}
    response = self.client.post(url, headers=self.headers, json=data)
    if response.status_code != 200:
        raise Exception(f"Error {response.status_code}: {response.text}")
    return response.json()

2. 添加 MCP 工具装饰器：

@mcp.tool()
def new_tool(param: str) -> Dict[str, Any]:
    """
    Tool description for AI assistants.

    Args:
        param: Parameter description

    Returns:
        Dictionary containing results
    """
    if scrapegraph_client is None:
        return {"error": "ScrapeGraph client not initialized. Please provide an API key."}

    try:
        return scrapegraph_client.new_tool(param)
    except Exception as e:
        return {"error": str(e)}

3. 使用 MCP Inspector 测试：

npx @modelcontextprotocol/inspector scrapegraph-mcp

4. 更新文档：

   • 将工具添加到此 README
   • 更新 .agent 文档

5. 提交拉取请求

开发工作流

1. Fork 仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 进行更改
4. 运行 lint 检查和类型检查
5. 使用 MCP Inspector 和 Claude Desktop 测试
6. 更新文档
7. 提交更改（git commit -m 'Add amazing feature'）
8. 推送到分支（git push origin feature/amazing-feature）
9. 发起拉取请求

代码风格

• 行长：100 个字符
• 类型提示：所有函数都必须提供
• 文档字符串：采用 Google 风格的文档字符串
• 错误处理：返回错误字典，不要在工具中引发异常
• Python 版本：目标版本为 3.13+

如需详细的开发指南，请参阅 .agent 文档。

文档

如需全面的开发者文档，请参阅：

• .agent/README.md - 完整的开发者文档索引
• .agent/system/project_architecture.md - 系统架构和设计
• .agent/system/mcp_protocol.md - MCP 协议集成详情

技术栈

核心框架

• Python 3.13+ - 支持类型提示的现代 Python
• FastMCP - 轻量级 MCP 服务框架
• httpx 0.24.0+ - 现代异步 HTTP 客户端

开发工具

• Ruff - 快速的 Python 代码检查和格式化工具
• mypy - 静态类型检查器
• Hatchling - 现代构建后端

部署

• Smithery - 自动化 MCP 服务部署
• Docker - 支持 Alpine Linux 的容器
• stdio transport - 标准 MCP 通信方式

API 集成

• ScrapeGraph AI API - 企业级网页抓取服务
• Base URL：https://v2-api.scrapegraphai.com/api
• Authentication：基于 API 密钥

许可证

本项目根据 MIT 许可证发行。详细条款和条件请参阅 LICENSE 文件。

致谢

特别感谢 tomekkorbak 实现了 oura-mcp-server，本项目以此为起点。

资源

官方链接

• ScrapeGraph AI 主页
• ScrapeGraph 控制台 - 获取 API 密钥
• ScrapeGraph API 文档
• GitHub 仓库

MCP 资源

• Model Context Protocol - 官方 MCP 规范
• FastMCP 框架 - 此服务使用的框架
• MCP Inspector - 测试工具
• Smithery - MCP 服务分发
• mcp-name: io.github.ScrapeGraphAI/scrapegraph-mcp

AI 助手集成

• Claude Desktop - 支持 MCP 的桌面应用
• Cursor - AI 驱动的代码编辑器

支持

• GitHub Issues - 报告错误或请求功能
• 开发者文档 - 全面的开发文档

---

由 ScrapeGraphAI 团队倾心打造 ❤️