ScrapeGraph AI

Web scraping impulsado por IA utilizando la API de ScrapeGraph AI. Requiere una clave de API.

Documentación

Servidor MCP de ScrapeGraph

ScrapegraphAI Logo

Un servidor Model Context Protocol (MCP) listo para producción que proporciona una integración perfecta con la API de ScrapeGraph AI. Este servidor permite a los modelos de lenguaje aprovechar capacidades avanzadas de web scraping impulsadas por IA con una fiabilidad de nivel empresarial.

API v2

Este servidor MCP está dirigido a la API v2 de ScrapeGraph (https://v2-api.scrapegraphai.com/api), alineado 1:1 con scrapegraph-py PR #84. La autenticación utiliza el encabezado SGAI-APIKEY. Las variables de entorno reflejan el SDK de Python:

SGAI_API_URL — anula la URL base (por defecto https://v2-api.scrapegraphai.com/api)
SGAI_TIMEOUT — tiempo de espera de solicitud en segundos (por defecto 120)
SGAI_API_KEY — clave de API (también se puede pasar a través de MCP scrapegraphApiKey o encabezado X-API-Key)

Alias heredados (aún admitidos): SCRAPEGRAPH_API_BASE_URL para SGAI_API_URL, SGAI_TIMEOUT_S para SGAI_TIMEOUT.

Características Clave

Scrape y extracción: scrape (POST /scrape, multi-formato), extract (POST /extract, URL + prompt)
Búsqueda: search (POST /search; num_results limitado a 3–20)
Crawl: Crawl asíncrono de múltiples páginas con crawl_start / crawl_get_status / crawl_stop / crawl_resume
Esquema: schema (POST /schema) — genera o aumenta un JSON Schema a partir de un prompt
Monitores: Trabajos programados a través de monitor_create, monitor_list, monitor_get, pausar/reanudar/eliminar, monitor_activity (historial de ticks paginado)
Cuenta: credits, history
Integración fácil: Claude Desktop, Cursor, Smithery, transporte HTTP
Documentación para desarrolladores: carpeta .agent/

Migración: v2 → v3

v3 renombra cada herramienta MCP que divergía de la documentación de la API v2. Renombrado estricto, sin alias.

v2 (antiguo)	v3 (nuevo)
`smartscraper`	`extract`
`searchscraper`	`search`
`smartcrawler_initiate`	`crawl_start`
`smartcrawler_fetch_results`	`crawl_get_status`
`sgai_history`	`history`
`generate_schema`	`schema`
`markdownify`	eliminado — usa `scrape` con `output_format="markdown"`

Inicio Rápido

1. Obtén tu Clave de API

Regístrate y obtén tu clave de API desde el Panel de ScrapeGraph

2. Instala con Smithery (Recomendado)

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

3. Comienza a Usar

Pregunta a Claude o Cursor:

"Convierte https://scrapegraphai.com a markdown"
"Extrae todos los precios de productos de esta página de comercio electrónico"
"Investiga los últimos avances en IA y resume los hallazgos"

¡Eso es todo! El servidor ya está disponible para tu asistente de IA.

Herramientas Disponibles

Herramienta	Rol
`scrape`	POST /scrape (`output_format`: markdown, html, screenshot, branding, links, images, summary)
`extract`	POST /extract (requiere `website_url` + `user_prompt`; opcional `output_schema`)
`search`	POST /search (`num_results` 1–20; admite `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 (consultar hasta `status: completed`)
`crawl_stop`, `crawl_resume`	POST /crawl/:id/stop \| resume
`schema`	POST /schema (genera o aumenta un JSON Schema a partir de un prompt)
`credits`	GET /credits
`history`	GET /history (paginado, filtro `service`)
`monitor_create`, `monitor_list`, `monitor_get`, `monitor_pause`, `monitor_resume`, `monitor_delete`	API /monitor
`monitor_activity`	GET /monitor/:id/activity (historial de ticks paginado: `id`, `createdAt`, `status`, `changed`, `elapsedMs`, `diffs`)

Eliminados: sitemap, agentic_scrapper, consulta de estado asíncrono y (en v3) markdownify — usa scrape con output_format="markdown".

Instrucciones de Configuración

Para utilizar este servidor, necesitarás una clave de API de ScrapeGraph. Sigue estos pasos para obtener una:

Navega al Panel de ScrapeGraph
Crea una cuenta y genera tu clave de API

Instalación Automatizada a través de Smithery

Para la instalación automatizada del Servidor de Integración de la API de ScrapeGraph usando Smithery:

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

Configuración de Claude Desktop

Actualiza tu archivo de configuración de Claude Desktop con la siguiente configuración (ubicado en la parte superior derecha de la página de Cursor):

(recuerda agregar tu clave de API dentro de la configuración)

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

El archivo de configuración se encuentra en:

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

Integración con Cursor

Agrega el servidor MCP de ScrapeGraphAI en la configuración:

Cursor MCP Integration

Uso del Servidor Remoto

Conéctate a nuestro servidor MCP alojado: ¡no se requiere instalación local!

[!ADVERTENCIA] El endpoint MCP heredado en https://mcp.scrapegraphai.com/mcp será obsoleto pronto. Las nuevas integraciones deben usar el endpoint MCP de reemplazo: https://sgai-mcp-main.onrender.com.

Configuración de Claude Desktop (Remoto)

Agrega esto a tu configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json en 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"
      ]
    }
  }
}

Configuración de Cursor (Remoto)

Cursor admite conexiones MCP HTTP nativas. Agrega a tu configuración MCP de Cursor (~/.cursor/mcp.json):

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

Beneficios del Servidor Remoto

Sin configuración local - Solo configura y comienza a usar
Siempre actualizado - Recibe automáticamente las últimas actualizaciones
Multiplataforma - Funciona en cualquier sistema operativo con Node.js

Uso Local

Para ejecutar el servidor MCP localmente para desarrollo o pruebas, sigue estos pasos:

Requisitos Previos

Python 3.13 o superior
Gestor de paquetes pip o uv
Clave de API de ScrapeGraph

Instalación

Clona el repositorio (si aún no lo has hecho):

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

Instala el paquete:

# Using pip
pip install -e .

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

Configura tu clave de 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

Ejecutando el Servidor Localmente

Puedes ejecutar el servidor directamente:

# Using the installed command
scrapegraph-mcp

# Or using Python module
python -m scrapegraph_mcp.server

El servidor se iniciará y se comunicará a través de stdio (entrada/salida estándar), que es el método de transporte MCP estándar.

Pruebas con MCP Inspector

Prueba tu servidor local usando la herramienta MCP Inspector:

npx @modelcontextprotocol/inspector python -m scrapegraph_mcp.server

Esto proporciona una interfaz web para probar todas las herramientas disponibles de forma interactiva.

Configurando Claude Desktop para el Servidor Local

Para usar tu servidor local con Claude Desktop, actualiza tu archivo de configuración:

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

Nota: Asegúrate de que Python esté en tu PATH. Puedes verificarlo ejecutando python --version en tu terminal.

Configurando Cursor para el Servidor Local

En la configuración MCP de Cursor, agrega un nuevo servidor con:

Comando: python
Argumentos: ["-m", "scrapegraph_mcp.server"]
Variables de Entorno: {"SGAI_API_KEY": "your-api-key-here"}

Solución de Problemas de Configuración Local

El servidor no se inicia:

Verifica que Python esté instalado: python --version
Comprueba que el paquete esté instalado: pip list | grep scrapegraph-mcp
Asegúrate de que la clave de API esté configurada: echo $SGAI_API_KEY (macOS/Linux) o echo %SGAI_API_KEY% (Windows)

Las herramientas no aparecen:

Revisa los registros de Claude Desktop:
- macOS: ~/Library/Logs/Claude/
- Windows: %APPDATA%\Claude\Logs\
Verifica que el servidor se inicie sin errores cuando se ejecuta directamente
Comprueba que el JSON de configuración sea válido

Errores de importación:

Reinstala el paquete: pip install -e . --force-reinstall
Verifica las dependencias: pip install -r requirements.txt (si está disponible)

Integración con Google ADK

El servidor MCP de ScrapeGraph se puede integrar con Google ADK (Kit de Desarrollo de Agentes) para crear agentes de IA con capacidades de web scraping.

Requisitos Previos

Python 3.13 o superior
Google ADK instalado
Clave de API de ScrapeGraph

Instalación

Instala Google ADK (si aún no está instalado):

pip install google-adk

Configura tu clave de API:

export SGAI_API_KEY=your-api-key-here

Ejemplo Básico de Integración

Crea un archivo de agente (por ejemplo, agent.py) con la siguiente configuración:

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']
        )
    ],
)

Opciones de Configuración

Configuración de Tiempo de Espera:

El tiempo de espera predeterminado es de 5 segundos, que puede ser demasiado corto para operaciones de web scraping
Recomendado: Configura `timeout=300.0
Ajusta según tu caso de uso (las operaciones de crawl pueden necesitar tiempos de espera aún más largos)

Filtrado de Herramientas:

Por defecto, todas las herramientas MCP registradas están expuestas al agente (consulta Herramientas Disponibles)
Usa tool_filter para limitar qué herramientas están disponibles:
```
tool_filter=['scrape', 'extract', 'search']
```

Configuración de la Clave de API:

Configúrala a través de la variable de entorno: export SGAI_API_KEY=your-key
O pásala directamente en el diccionario env: 'SGAI_API_KEY': 'your-key-here'
Se recomienda el enfoque de variable de entorno por seguridad

Ejemplo de Uso

Una vez configurado, tu agente puede usar lenguaje natural para interactuar con las herramientas de web scraping:

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

Para más información sobre Google ADK, visita la documentación oficial.

Ejemplos de Casos de Uso

El servidor permite consultas sofisticadas en varios escenarios de scraping:

Scraping de Página Única

Markdownify: "Convierte la página de documentación de ScrapeGraph a markdown"
Extract: "Extrae todos los nombres de productos, precios y calificaciones de esta página de comercio electrónico"
Extract con desplazamiento: "Haz scraping de esta página de desplazamiento infinito con 5 desplazamientos y extrae todos los elementos"
Scrape básico: "Obtén el contenido HTML de esta página con mucho JavaScript con renderizado completo"

Búsqueda e Investigación

Search: "Investiga y resume los desarrollos recientes en web scraping impulsado por IA"
Search: "Busca los 5 mejores artículos sobre marcos de aprendizaje automático y extrae información clave"
Search: "Encuentra noticias recientes sobre GPT-4 y proporciona un resumen estructurado"
Search: v2 no aplica time_range; formula consultas para sesgar la actualidad en lenguaje natural en su lugar

Análisis de Sitios Web

Usa crawl_start junto con crawl_get_status para mapear y capturar contenido de múltiples páginas; no hay una herramienta separada de sitemap en v2.

Crawl de Múltiples Páginas

Crawl: "Haz crawl del blog en modo markdown y consulta hasta que se complete"
Para campos estructurados por página, ejecuta extract en URLs individuales (o monitor_create en un horario programado)

Monitores y Cuenta

Monitor: "Ejecuta este prompt de extracción en https://example.com todos los días a las 9am" (monitor_create con intervalo)
Credits / history: credits, history
Scraper Agéntico: "Ejecuta un flujo de trabajo complejo: inicia sesión, navega a informes, descarga datos y extrae estadísticas resumidas"

Manejo de Errores

El servidor implementa un manejo robusto de errores con mensajes de error detallados y accionables para:

Problemas de autenticación de API
Estructuras de URL malformadas
Fallos de conectividad de red
Limitación de velocidad y gestión de cuotas

Problemas Comunes

Conexión Específica de Windows

Cuando se ejecuta en sistemas Windows, es posible que necesites usar el siguiente comando para conectarte al servidor MCP:

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

Esto asegura una ejecución adecuada en el entorno de Windows.

Otros Problemas Comunes

"Cliente de ScrapeGraph no inicializado"

Causa: Falta la clave de API
Solución: Configura la variable de entorno SGAI_API_KEY o proporciónala a través de --config

"Error 401: No autorizado"

Causa: Clave de API inválida
Solución: Verifica tu clave de API en el Panel de ScrapeGraph "Error 402: Payment Required"
Causa: Créditos insuficientes
Solución: Añade créditos a tu cuenta de ScrapeGraph

El rastreo no devuelve resultados

Causa: Aún se está procesando (operación asíncrona)
Solución: Sigue consultando crawl_get_status() hasta que el estado sea "completed"

Las herramientas no aparecen en Claude Desktop

Causa: El servidor no se inicia o hay un error de configuración
Solución: Revisa los registros de Claude en ~/Library/Logs/Claude/ (macOS) o %APPDATA%\Claude\Logs\ (Windows)

Para solución de problemas detallada, consulta la documentación de .agent.

Desarrollo

Requisitos previos

Python 3.13 o superior
Gestor de paquetes pip o uv
Clave API de ScrapeGraph

Instalación desde el código fuente

# 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

Pruebas con MCP Inspector

Prueba tu servidor localmente usando la herramienta MCP Inspector:

npx @modelcontextprotocol/inspector scrapegraph-mcp

Esto proporciona una interfaz web para probar todas las herramientas disponibles.

Calidad del código

Linting:

ruff check src/

Verificación de tipos:

mypy src/

Verificación de formato:

ruff format --check src/

Estructura del proyecto

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

Contribuciones

¡Damos la bienvenida a las contribuciones! Así es como puedes ayudar:

Añadir una nueva herramienta

Añade el método a la clase ScapeGraphClient en 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()

Añade el decorador de herramienta 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)}

Prueba con MCP Inspector:

npx @modelcontextprotocol/inspector scrapegraph-mcp

Actualiza la documentación:
- Añade la herramienta a este README
- Actualiza la documentación de .agent
Envía una solicitud de extracción

Flujo de trabajo de desarrollo

Haz un fork del repositorio
Crea una rama de características (git checkout -b feature/amazing-feature)
Realiza tus cambios
Ejecuta el linting y la verificación de tipos
Prueba con MCP Inspector y Claude Desktop
Actualiza la documentación
Confirma tus cambios (git commit -m 'Add amazing feature')
Sube a la rama (git push origin feature/amazing-feature)
Abre una solicitud de extracción

Estilo de código

Longitud de línea: 100 caracteres
Anotaciones de tipo: Obligatorias para todas las funciones
Docstrings: Docstrings estilo Google
Manejo de errores: Devuelve diccionarios de error, no lances excepciones en las herramientas
Versión de Python: Objetivo 3.13+

Para pautas de desarrollo detalladas, consulta la documentación de .agent.

Documentación

Para documentación completa para desarrolladores, consulta:

.agent/README.md - Índice completo de documentación para desarrolladores
.agent/system/project_architecture.md - Arquitectura y diseño del sistema
.agent/system/mcp_protocol.md - Detalles de integración del protocolo MCP

Pila tecnológica

Marco principal

Python 3.13+ - Python moderno con anotaciones de tipo
FastMCP - Marco ligero de servidor MCP
httpx 0.24.0+ - Cliente HTTP asíncrono moderno

Herramientas de desarrollo

Ruff - Linter y formateador rápido de Python
mypy - Verificador de tipos estático
Hatchling - Backend de compilación moderno

Despliegue

Smithery - Despliegue automatizado de servidores MCP
Docker - Soporte de contenedores con Alpine Linux
Transporte stdio - Comunicación MCP estándar

Integración de API

API de ScrapeGraph AI - Servicio empresarial de web scraping
URL base: https://v2-api.scrapegraphai.com/api
Autenticación: Basada en clave API

Licencia

Este proyecto se distribuye bajo la Licencia MIT. Para términos y condiciones detallados, consulta el archivo LICENSE.

Agradecimientos

Agradecimiento especial a tomekkorbak por su implementación de oura-mcp-server, que sirvió como punto de partida para este repositorio.

Recursos

Enlaces oficiales

Página principal de ScrapeGraph AI
Panel de ScrapeGraph - Obtén tu clave API
Documentación de la API de ScrapeGraph
Repositorio de GitHub

Recursos MCP

Model Context Protocol - Especificación oficial de MCP
Marco FastMCP - Marco utilizado por este servidor
MCP Inspector - Herramienta de prueba
Smithery - Distribución de servidores MCP
mcp-name: io.github.ScrapeGraphAI/scrapegraph-mcp

Integración con asistentes de IA

Claude Desktop - Aplicación de escritorio con soporte MCP
Cursor - Editor de código impulsado por IA

Soporte

Problemas de GitHub - Reporta errores o solicita funciones
Documentación para desarrolladores - Documentación completa para desarrolladores

Hecho con ❤️ por el equipo de ScrapeGraphAI