API VEGA

ScrapeGraph MCP Server

Готовый к продакшену сервер Model Context Protocol (MCP), обеспечивающий бесшовную интеграцию с API ScrapeGraph AI. Сервер позволяет языковым моделям задействовать продвинутые возможности веб-скрейпинга на базе ИИ с надёжностью корпоративного уровня.

Содержание

  • Ключевые возможности

  • Быстрый старт

  • Доступные инструменты

  • Инструкция по настройке

  • Использование удалённого сервера

  • Локальное использование

  • Интеграция с Google ADK

  • Примеры использования

  • Обработка ошибок

  • Частые проблемы

  • Разработка

  • Участие в проекте

  • Документация

  • Технологический стек

  • Лицензия

API v2

Этот MCP-сервер работает с ScrapeGraph API v2 (https://v2-api.scrapegraphai.com/api) и один в один соответствует

scrapegraph-py PR #84. Аутентификация выполняется через заголовок

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 /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 переименованы все MCP-инструменты, названия которых расходились с документацией API v2. Жёсткое переименование, без псевдонимов.

v2 (старое)v3 (новое)
smartscraperextract
searchscrapersearch
smartcrawler_initiatecrawl_start
smartcrawler_fetch_resultscrawl_get_status
sgai_historyhistory
generate_schemaschema
markdownifyудалён — используйте scrape с output_format="markdown"

Быстрый старт

1. Получите API-ключ

Зарегистрируйтесь и получите API-ключ в ScrapeGraph Dashboard

2. Установите через Smithery (рекомендуется)

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

3. Начните работу

Попросите Claude или Cursor:

  • «Конвертируй https://scrapegraphai.com в markdown»

  • «Извлеки все цены на товары с этой страницы интернет-магазина»

  • «Изучи последние новости в области ИИ и обобщи результаты»

Готово! Теперь сервер доступен вашему ИИ-ассистенту.

Доступные инструменты

ИнструментНазначение
scrapePOST /scrape (output_format: markdown, html, screenshot, branding, links, images, summary)
extractPOST /extract (требуются website_url и user_prompt; опционально output_schema)
searchPOST /search (num_results 1–20; поддерживает country_search, time_range, output_schema)
crawl_startPOST /crawl — extraction_mode: markdown / html / links / images / summary / branding / screenshot
crawl_get_statusGET /crawl/:id (опрос до status: completed)
crawl_stop, crawl_resumePOST /crawl/:id/stop | resume
schemaPOST /schema (генерация или дополнение JSON Schema по промпту)
creditsGET /credits
historyGET /history (с пагинацией, фильтр service)
monitor_create, monitor_list, monitor_get, monitor_pause, monitor_resume, monitor_deleteAPI /monitor
monitor_activityGET /monitor/:id/activity (постраничная история проверок: id, createdAt, status, changed, elapsedMs, diffs)

Удалены: sitemap, agentic_scrapper, опрос асинхронных статусов и (в v3) markdownify — вместо них используйте scrape с output_format="markdown".

Инструкция по настройке

Для работы с сервером потребуется API-ключ ScrapeGraph. Получить его можно следующим образом:

  • Перейдите в ScrapeGraph Dashboard

  • Создайте аккаунт и сгенерируйте API-ключ

Автоматическая установка через Smithery

Для автоматической установки сервера интеграции ScrapeGraph API с помощью Smithery:

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

Добавьте MCP-сервер ScrapeGraphAI в настройках:

Использование удалённого сервера

Подключайтесь к нашему хостинговому MCP-серверу — локальная установка не требуется!

Внимание

Устаревший MCP-эндпоинт https://mcp.scrapegraphai.com/mcp скоро будет выведен из эксплуатации. Для новых интеграций используйте заменяющий MCP-эндпоинт:

https://sgai-mcp-main.onrender.com.

Конфигурация Claude Desktop (удалённый сервер)

Добавьте этот блок в конфигурацию Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json на macOS):

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

Конфигурация Cursor (удалённый сервер)

Cursor поддерживает нативные HTTP-подключения к MCP. Добавьте следующее в настройки MCP Cursor (~/.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

  • API-ключ ScrapeGraph

Установка

  • Клонируйте репозиторий (если ещё не сделали этого):
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

Он предоставляет веб-интерфейс для интерактивного тестирования всех доступных инструментов.

Настройка 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 для локального сервера

В настройках MCP в Cursor добавьте новый сервер со следующими параметрами:

  • Command: python

  • Args: ["-m", "scrapegraph_mcp.server"]

  • Environment Variables: {"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

MCP-сервер ScrapeGraph можно интегрировать с Google ADK (Agent Development Kit), чтобы создавать AI-агентов с возможностями веб-скрапинга.

Предварительные требования

  • Python 3.13 или выше

  • Установленный Google ADK

  • API-ключ ScrapeGraph

Установка

  • Установите 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

# 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 (см. раздел «Доступные инструменты»)

  • Используйте 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»

  • Extract: «Извлеки названия, цены и рейтинги всех товаров с этой страницы интернет-магазина»

  • Extract с прокруткой: «Собери данные с этой страницы с бесконечной прокруткой, выполнив 5 прокруток, и извлеки все элементы»

  • Basic Scrape: «Получи HTML-содержимое этой страницы с большим объёмом JavaScript и полным рендерингом»

Поиск и исследования

  • Search: «Изучи и обобщи последние разработки в области веб-скрапинга на базе AI»

  • Search: «Найди 5 лучших статей о фреймворках машинного обучения и извлеки ключевые выводы»

  • Search: «Найди свежие новости о GPT-4 и подготовь структурированное резюме»

  • Search: v2 не применяет time_range; вместо этого формулируйте запросы так, чтобы они естественным образом смещали результаты в сторону свежести

Анализ сайтов

  • Используйте crawl_start вместе с crawl_get_status, чтобы составить карту и собрать контент с нескольких страниц; отдельного инструмента sitemap в v2 нет.

Обход нескольких страниц

  • Crawl: «Обойди блог в режиме markdown и опрашивай статус до завершения»

  • Для структурированных полей по каждой странице запускайте extract на отдельных URL (либо monitor_create по расписанию)

Мониторы и аккаунт

  • Monitor: «Запускай этот extract-промпт на https://example.com каждый день в 9:00» (monitor_create с интервалом)

  • Credits / history: 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 client not initialized»

  • Причина: отсутствует API-ключ

  • Решение: задайте переменную окружения SGAI_API_KEY или передайте ключ через --config

«Error 401: Unauthorized»

«Error 402: Payment Required»

  • Причина: недостаточно кредитов

  • Решение: пополните баланс кредитов в вашем аккаунте ScrapeGraph

Crawl не возвращает результаты

  • Причина: операция всё ещё обрабатывается (асинхронный процесс)

  • Решение: продолжайте опрашивать crawl_get_status() до получения статуса «completed»

Инструменты не отображаются в Claude Desktop

  • Причина: сервер не запускается или ошибка в конфигурации

  • Решение: проверьте логи Claude по пути ~/Library/Logs/Claude/ (macOS) или %APPDATA%\Claude\Logs\ (Windows)

Подробное руководство по устранению неполадок см. в документации .agent.

Разработка

Предварительные требования

  • Python 3.13 или выше

  • менеджер пакетов pip или uv

  • API-ключ ScrapeGraph

Установка из исходного кода

# 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

Он предоставляет веб-интерфейс, в котором можно проверить все доступные инструменты.

Качество кода

Линтинг:

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

Участие в разработке

Мы приветствуем любой вклад в проект! Вот как вы можете помочь:

Добавление нового инструмента

  • Добавьте метод в класс ScapeGraphClient в файле server.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()
  • Добавьте декоратор 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

  • Обновите документацию:

  • Отправьте pull request

Процесс разработки

  • Сделайте форк репозитория

  • Создайте ветку для новой функциональности (git checkout -b feature/amazing-feature)

  • Внесите необходимые изменения

  • Запустите линтинг и проверку типов

  • Протестируйте с помощью MCP Inspector и Claude Desktop

  • Обновите документацию

  • Закоммитьте изменения (git commit -m 'Add amazing feature')

  • Отправьте ветку в удалённый репозиторий (git push origin feature/amazing-feature)

  • Откройте Pull Request

Стиль кода

  • Длина строки: 100 символов

  • Аннотации типов: обязательны для всех функций

  • Docstrings: оформляются в стиле Google

  • Обработка ошибок: возвращайте словари с описанием ошибки вместо выбрасывания исключений в инструментах

  • Версия Python: 3.13 и выше

Подробные рекомендации по разработке приведены в документации .agent.

Документация

Полная документация для разработчиков доступна по следующим ссылкам:

Технологический стек

Основной фреймворк

  • 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 — корпоративный сервис веб-скрейпинга

  • Базовый URL: https://v2-api.scrapegraphai.com/api

  • Аутентификация: с использованием 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

Поддержка

Сделано с ❤️ командой ScrapeGraphAI