抓取图谱-mcp

Name: 抓取图谱-mcp
Author: ScrapeGraphAI

作者：ScrapeGraphAI45 星标更新：2025-11-20

安装使用来源：spider==github.com

项目介绍

技术文档摘要

ScrapeGraph MCP Server

一个生产就绪的 Model Context Protocol (MCP) 服务器，提供与 ScrapeGraph AI API 的无缝集成。此服务器使语言模型能够利用先进的AI驱动的网络爬取功能，并具有企业级可靠性。

关键特性

8个强大的工具：从简单的Markdown转换到复杂的多页爬取和代理工作流
AI驱动的数据提取：通过自然语言提示智能地提取结构化数据
多页爬取：SmartCrawler支持异步爬取，具有可配置的深度和页面限制
无限滚动支持：处理动态内容加载，具有可配置的滚动计数
JavaScript渲染：完全支持JavaScript密集型网站
灵活的输出格式：以Markdown、结构化JSON或自定义模式获取结果
易于集成：与Claude Desktop、Cursor以及任何兼容MCP的客户端无缝工作
企业级：强大的错误处理、超时管理和经过生产测试的可靠性
简单部署：通过Smithery一键安装或手动设置
全面文档：详细的开发者文档位于.agent/文件夹中

快速开始

1. 获取您的API密钥

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

2. 使用Smithery安装（推荐）

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

3. 开始使用

询问Claude或Cursor：

"将https://scrapegraphai.com转换为Markdown"
"从这个电子商务页面提取所有产品价格"
"研究最新的AI发展并总结发现"

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

可用工具

该服务器提供了8个企业级工具用于AI驱动的网络爬取：

核心爬取工具

1. `markdownify`

将任何网页转换为干净、结构化的Markdown格式。

markdownify(website_url: str)

积分：每次请求2分
用例：快速提取网页内容为Markdown

2. `smartscraper`

利用AI从任何网页中提取结构化数据，支持无限滚动。

smartscraper(
    user_prompt: str,
    website_url: str,
    number_of_scrolls: int = None,
    markdown_only: bool = None
)

积分：10+（基础）+基于滚动的变量
用例：带有自定义提示的AI驱动的数据提取

3. `searchscraper`

执行AI驱动的网络搜索，具有结构化、可操作的结果。

searchscraper(
    user_prompt: str,
    num_results: int = None,
    number_of_scrolls: int = None
)

积分：变量（3-20个网站×10积分）
用例：多源研究和数据聚合

高级爬取工具

4. `scrape`

基本爬取端点，用于获取页面内容，可选支持重载JavaScript。

scrape(website_url: str, render_heavy_js: bool = None)

用例：支持JS渲染的简单页面内容获取

5. `sitemap`

提取任何网站的站点地图URL和结构。

sitemap(website_url: str)

用例：网站结构分析和URL发现

多页爬取

6. `smartcrawler_initiate`

启动智能多页网络爬取（异步操作）。

smartcrawler_initiate(
    url: str,
    prompt: str = None,
    extraction_mode: str = "ai",
    depth: int = None,
    max_pages: int = None,
    same_domain_only: bool = None
)

AI提取模式：每页10积分 - 提取结构化数据
Markdown模式：每页2积分 - 转换为Markdown
返回：request_id用于轮询
用例：大规模网站爬取和数据提取

7. `smartcrawler_fetch_results`

从异步爬取操作中检索结果。

smartcrawler_fetch_results(request_id: str)

返回：当爬取完成时的状态和结果
用例：轮询爬取完成并检索结果

智能代理驱动的爬取

8. `agentic_scrapper`

运行高级代理爬取工作流程，具有可定制步骤和结构化输出模式。

agentic_scrapper(
    url: str,
    user_prompt: str = None,
    output_schema: dict = None,
    steps: list = None,
    ai_extraction: bool = None,
    persistent_session: bool = None,
    timeout_seconds: float = None
)

用例：具有自定义模式和持久会话的复杂多步骤工作流程

安装说明

要使用此服务器，您需要一个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服务器，请遵循以下步骤：

先决条件

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

安装

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

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

安装包：

# 使用pip
pip install -e .

# 或使用uv（更快）
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

在本地运行服务器

您可以直接运行服务器：

# 使用已安装命令
scrapegraph-mcp

# 或使用Python模块
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（代理开发工具包）集成，创建具有网络爬取能力的AI代理。

先决条件

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

安装

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

pip install google-adk

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

# ScrapeGraph MCP服务器目录路径
SCRAPEGRAPH_MCP_PATH = "/path/to/scrapegraph-mcp"

# 服务器.py文件路径
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='使用ScrapeGraph AI帮助用户进行网络爬取和数据提取。'
                '您可以将网页转换为Markdown，使用AI提取结构化数据，'
                '执行网络搜索，爬取多个页面，并自动化复杂的爬取工作流程。',
    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,)
            ),
            # 可选：过滤MCP服务器暴露的哪些工具
            # tool_filter=['markdownify', 'smartscraper', 'searchscraper']
        )
    ],
)

配置选项

超时设置：

默认超时为5秒，对于网络爬取操作可能太短
推荐：设置timeout=300.0
根据您的用例调整（爬取操作可能需要更长的超时时间）

工具过滤：

默认情况下，所有8个工具都暴露给代理

使用tool_filter限制可用的工具：

tool_filter=['markdownify', 'smartscraper', 'searchscraper']

API密钥配置：

通过环境变量设置：export SGAI_API_KEY=your-key
或直接传递到env字典：'SGAI_API_KEY': 'your-key-here'
推荐使用环境变量方法以提高安全性

使用示例

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

# 代理现在可以处理如下查询：
# - "将https://example.com转换为Markdown"
# - "从这个电子商务页面提取所有产品价格"
# - "搜索最近关于AI驱动的网络爬取的研究并总结"
# - "爬取这个文档站点并提取所有API端点"

有关Google ADK的更多信息，请访问官方文档。

示例用例

服务器支持各种爬取场景中的复杂查询：

单页爬取

Markdownify："将ScrapeGraph文档页面转换为Markdown"
SmartScraper："从这个电子商务页面提取所有产品名称、价格和评分"
SmartScraper带滚动："滚动5次并从这个无限滚动页面抓取所有项目"
基本Scrape："获取这个JavaScript密集型页面的HTML内容，完全渲染"

搜索和研究

SearchScraper："研究并总结最近关于AI驱动的网络爬取的发展"
SearchScraper："搜索关于机器学习框架的前5篇文章并提取关键见解"
SearchScraper："查找关于GPT-4的最新新闻并提供结构化摘要"

网站分析

Sitemap："从ScrapeGraph网站提取完整的站点地图结构"
Sitemap："发现这个博客站点上的所有URL"

多页爬取

SmartCrawler（AI模式）："爬取整个文档站点并提取所有API端点及其描述"
SmartCrawler（Markdown模式）："将博客中的所有页面转换为Markdown，最多2层深"
SmartCrawler："从电子商务网站提取所有产品信息，最大100页，仅限同一域"

高级代理爬取

Agentic Scraper："导航多步认证表单并提取用户仪表盘数据"
Agentic Scraper带模式："跟随分页链接并编译带有模式的数据集：{标题，作者，日期，内容}"
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提供

“错误401：未授权”

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

“错误402：支付所需”

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

SmartCrawler未返回结果

原因：仍在处理（异步操作）
解决方案：继续轮询smartcrawler_fetch_results()直到状态为“已完成”

工具未出现在Claude Desktop中

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

有关详细的故障排除，请参阅[.agent文档](.agent

抓取图谱-mcp

项目介绍

技术文档摘要

ScrapeGraph MCP Server

目录

关键特性

快速开始

1. 获取您的API密钥

2. 使用Smithery安装（推荐）

3. 开始使用

可用工具

核心爬取工具

1. markdownify

2. smartscraper

3. searchscraper

高级爬取工具

4. scrape

5. sitemap

多页爬取

6. smartcrawler_initiate

7. smartcrawler_fetch_results

智能代理驱动的爬取

8. agentic_scrapper

安装说明

通过Smithery自动安装

Claude Desktop配置

Cursor集成

本地使用

先决条件

安装

在本地运行服务器

使用MCP Inspector测试

配置Claude Desktop以使用本地服务器

在Cursor中配置本地服务器

本地设置故障排除

Google ADK集成

先决条件

安装

基本集成示例

配置选项

使用示例

示例用例

单页爬取

搜索和研究

网站分析

多页爬取

高级代理爬取

错误处理

常见问题

Windows特定连接

其他常见问题

1. `markdownify`

2. `smartscraper`

3. `searchscraper`

4. `scrape`

5. `sitemap`

6. `smartcrawler_initiate`

7. `smartcrawler_fetch_results`

8. `agentic_scrapper`