ScrapeGraph MCP

ScrapeGraph MCP服务器

  ](https://smithery.ai/server/@ScrapeGraphAI/scrapegraph-mcp)

生产准备就绪 模型上下文协议 （MCP）服务器，提供与 ScrapeGraph AI API该服务器使语言模型能够利用先进的人工智能网络抓取功能，具有企业级的可靠性。

目录

• 主要特点
• 快速开始
• 可用工具
• 安装说明
• 远程服务器使用情况
• 本地使用
• 谷歌ADK集成
• 示例用例
• 错误处理
• 常见问题
• 发展
• 贡献
• 文档
• 技术栈
• 许可证

API v2

此MCP服务器的目标 ScrapeGraph API v2 (https://v2-api.scrapegraphai.com/api)，与1:1对齐 刮片py PR#84.Auth使用 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 头球

遗留别名（仍受尊重）： SCRAPEGRAPH_API_BASE_URL 为了 SGAI_API_URL, SGAI_TIMEOUT_S 为了 SGAI_TIMEOUT.

主要特点

• 刮除和提取: scrape （POST/刮擦、多格式）， extract （POST/提取，URL+提示）
• 搜索: search （POST/搜索； 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工具。 硬重命名，没有别名。

快速开始

1.获取API密钥

注册并从获取您的API密钥 ScrapeGraph仪表板

2.使用Smithery安装（推荐）

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

3.开始使用

请问克劳德或Cursor：

• “转换https://scrapegraphai.com降价”
• “从该电子商务页面提取所有产品价格”
• “研究最新的人工智能发展并总结研究结果”

就是这样！服务器现在可供您的AI助手使用。

可用工具

远离的： sitemap, agentic_scrapper、异步状态轮询，以及（在v3中） markdownify --使用 scrape 和 output_format="markdown".

安装说明

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

1. 导航到 ScrapeGraph仪表板
2. 创建帐户并生成您的API密钥

通过Smithery自动安装

用于ScrapeGraph API集成服务器的自动安装，使用 铁匠铺:

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

Claude桌面配置

使用以下设置更新您的Claude Desktop配置文件（位于光标页面的右上角）：

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

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

配置文件位于：

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

光标集成

在设置中添加ScrapeGraphaAI MCP服务器：

Cursor MCP Integration

远程服务器使用情况

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

Claude桌面配置（远程）

将此添加到您的Claude Desktop配置中(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "scrapegraph-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote@0.1.25",
        "https://scrapegraph-mcp.onrender.com/mcp",
        "--header",
        "X-API-Key:YOUR_API_KEY"
      ]
    }
  }
}

光标配置（远程）

Cursor支持本机HTTP MCP连接。添加到光标MCP设置(~/.cursor/mcp.json):

{
  "mcpServers": {
    "scrapegraph-mcp": {
      "url": "https://scrapegraph-mcp.onrender.com/mcp",
      "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

1. 安装软件包:

# Using pip
pip install -e .

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

1. 设置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检验员测试

使用MCP检查器工具测试本地服务器：

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"
            }
        }
    }
}

视窗 (%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的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）

工具未出现：

• 检查克劳德桌面日志：

- macOS： ~/Library/Logs/Claude/ - 窗户： %APPDATA%\Claude\Logs\

• 验证服务器在直接运行时启动时没有错误
• 检查配置JSON是否有效

导入错误：

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

谷歌ADK集成

ScrapeGraph MCP服务器可以与 Google ADK（代理开发工具包） 创建具有网络抓取功能的AI代理。

先决条件

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

安装

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

pip install google-adk

1. 设置API密钥:

export SGAI_API_KEY=your-api-key-here

基本集成示例

创建代理文件（例如。， 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秒，对于web抓取操作来说可能太短
• 建议：设置\`timeout=300.0
• 根据您的用例进行调整（爬行操作可能需要更长的超时时间）

工具筛选：

• 默认情况下，所有注册的MCP工具都向代理公开（请参阅 可用工具)
• 使用 tool_filter 限制可用的工具：

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

API密钥配置：

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

用法示例

配置后，您的代理可以使用自然语言与网络抓取工具进行交互：

# 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内容，并进行完整渲染”

搜索和研究

• 搜索：“研究和总结人工智能网络抓取的最新进展”
• 搜索：“搜索关于机器学习框架的前5篇文章并提取关键见解”
• 搜索：“查找GPT-4的最新消息并提供结构化摘要”
• 搜索：v2不适用 time_range；短语查询偏向自然语言中的近因性

网站分析

• 使用 crawl_start 加 crawl_get_status 绘制和捕获多页内容；没有单独的 网站地图 v2上的工具。

多页面爬行

• 爬行：“以markdown模式抓取博客并轮询，直到完成”
• 对于每页的结构化字段，请运行 extract 在单个URL上（或 monitor_create 按时间表）

监视器和帐户

• 监视器：“在上运行此提取提示https://example.com每天早上9点”(monitor_create 间隔）
• 学分/历史: credits, history
• 代理刮刀：“执行复杂的工作流：登录、导航到报告、下载数据和提取摘要统计信息”

错误处理

服务器通过详细的、可操作的错误消息实现了稳健的错误处理，用于：

• 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

“错误401：未经授权”

• 原因：API密钥无效
• 解决方案：在上验证您的API密钥 ScrapeGraph仪表板

“错误402：需要付款”

• 原因：学分不足
• 解决方案：向您的ScrapeGraph帐户添加积分

爬行不返回结果

• 原因：仍在处理（异步操作）
• 解决方案：继续投票 crawl_get_status() 直到状态“完成”

工具未出现在Claude Desktop中

• 原因：服务器未启动或配置错误
• 解决方案：在以下网址查看克劳德日志 ~/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检验员测试

使用MCP检查器工具在本地测试您的服务器：

npx @modelcontextprotocol/inspector scrapegraph-mcp

这提供了一个web界面来测试所有可用的工具。

代码质量

Linting：

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. 添加方法 ScapeGraphClient 类 在 服务器.py:

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

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

1. 使用MCP检查员进行测试:

npx @modelcontextprotocol/inspector scrapegraph-mcp

1. 更新文档:

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

1. 提交拉取请求

开发工作流程

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 进行更改
4. 运行linting和类型检查
5. 使用MCP Inspector和Claude Desktop进行测试
6. 更新文档
7. 提交您的更改(git commit -m 'Add amazing feature')
8. 推到分支(git push origin feature/amazing-feature)
9. 打开拉取请求

代码的风格

• 行宽：100个字符
• 键入提示：所有功能都需要
• 文档字符串：谷歌风格的文档字符串
• 错误处理：返回错误字典，不要在工具中引发异常
• Python 版本：目标3.13+

有关详细的开发指南，请参阅 .agent文档.

文档

有关全面的开发人员文档，请参阅：

• .agent/README.md -完整的开发人员文档索引
• .agent/system/project_architecture.md -系统架构与设计
• .agent/系统/mcprotocol.md -MCP协议集成详细信息

技术栈

核心框架

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

开发工具

• 拉夫 -快速Python linter和格式化程序
• 米皮 -静态类型检查器
• 孵化 -现代构建后端

部署

• 铁匠铺 -自动化MCP服务器部署
• 码头工人 -Alpine Linux的容器支持
• stdio传输 -标准MCP通信

API集成

• ScrapeGraph AI API -企业网络抓取服务
• 基本URL: https://v2-api.scrapegraphai.com/api
• 认证：基于API密钥

许可证

该项目在MIT许可证下分发。有关详细的条款和条件，请参阅许可文件。

致谢

资源

官方链接

• ScrapeGraph AI主页
• ScrapeGraph仪表板 -获取API密钥
• ScrapeGraph API文档

MCP资源

• 模型上下文协议 -MCP官方规范
• FastMCP框架 -此服务器使用的框架
• MCP检查员 -测试工具
• 铁匠铺 -MCP服务器分布
• mcp名称：io.github。ScrapeGraphAI/scrapegraph mcp

AI助手集成

• 克劳德桌面版 -支持MCP的桌面应用程序
• 光标 -AI驱动的代码编辑器

支持

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

______________________________________________________________________

由...制作❤️ 通过 报废石墨AI 团队