ScrapeGraph MCP Server

Name: ScrapeGraph MCP Server
Author: ScrapeGraphAI

本地服务

github.com/ScrapeGraphAI浏览器自动化11915 周前更新

代码仓库

关于 ScrapeGraph MCP Server

ScrapeGraph MCP Server 是一个 MCP 服务，用于连接 ScrapeGraph AI API，提供基于 AI 的网页抓取、提取、搜索与爬取能力。适用于需要让语言模型读取网页内容的开发者与研究人员。支持本地运行与远程托管两种方式。

主要功能

01抓取页面并输出 markdown、html 等格式
02基于提示词从网页提取结构化数据
03搜索网页并返回结果
04异步多页爬取与状态查询
05定时监控任务与credits查询

适用场景

01将网页转换为 markdown 供 LLM 使用
02从电商页面批量提取商品价格
03爬取文档站点并整理其中的 API 信息

MCP 相关

该项目是 MCP 服务，向 MCP 客户端暴露 scrape、extract、search、crawl 等工具，并支持远程服务与本地运行。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "scrapegraph": {
      "command": "npx",
      "args": [
        "-y",
        "@smithery/cli"
      ]
    }
  }
}

启动命令npx -y @smithery/cli

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@smithery/clistdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

ScrapeGraph MCP Server

ScrapegraphAI 标志

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

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 密钥。请按照以下步骤获取：

前往 ScrapeGraph 控制台
创建账户并生成 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 服务：

Cursor 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 密钥

安装

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

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

安装软件包：

# Using pip
pip install -e .

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

设置您的 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 密钥

安装

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

pip install google-adk

设置 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

参与贡献

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

添加新工具

在 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()

添加 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)}

使用 MCP Inspector 测试：

npx @modelcontextprotocol/inspector scrapegraph-mcp

更新文档：
- 将工具添加到此 README
- 更新 .agent 文档
提交拉取请求

开发工作流

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

代码风格

行长：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，本项目以此为起点。

资源

官方链接

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 团队倾心打造 ❤️

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

ScrapeGraph MCP Server

关于 ScrapeGraph MCP Server

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

ScrapeGraph MCP Server

目录

API v2

主要功能

迁移：v2 → v3

快速开始

1. 获取 API 密钥

2. 使用 Smithery 安装（推荐）

3. 开始使用

可用工具

设置说明

通过 Smithery 自动安装

Claude Desktop 配置

Cursor 集成

远程服务用法

Claude Desktop 配置（远程）

Cursor 配置（远程）

远程服务的优势

本地用法

先决条件

安装

在本地运行服务

使用 MCP Inspector 进行测试

配置 Claude Desktop 以使用本地服务

配置 Cursor 以使用本地服务

本地设置故障排除

Google ADK 集成

前提条件

安装

基本集成示例

配置选项

使用示例

示例用例

单页抓取

搜索与研究

网站分析

多页爬取

监控和账户

错误处理

常见问题

Windows 特定连接

其他常见问题

开发

前置条件

从源代码安装

使用 MCP Inspector 测试

代码质量

项目结构

参与贡献

添加新工具

开发工作流

代码风格

文档

技术栈

核心框架

开发工具

部署

API 集成

许可证

致谢

资源

官方链接

MCP 资源

AI 助手集成

支持

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？