ScrapeGraph AI

Web scraping com inteligência artificial usando a API do ScrapeGraph AI. Requer uma chave de API.

Documentação

Servidor MCP ScrapeGraph

ScrapegraphAI Logo

Um servidor Model Context Protocol (MCP) pronto para produção que fornece integração perfeita com a API do ScrapeGraph AI. Este servidor permite que modelos de linguagem aproveitem recursos avançados de raspagem web com inteligência artificial e confiabilidade de nível empresarial.

API v2

Este servidor MCP tem como alvo a ScrapeGraph API v2 (https://v2-api.scrapegraphai.com/api), alinhado 1:1 com scrapegraph-py PR #84. A autenticação usa o cabeçalho SGAI-APIKEY. As variáveis de ambiente espelham o SDK Python:

SGAI_API_URL — substitui a URL base (padrão https://v2-api.scrapegraphai.com/api)
SGAI_TIMEOUT — tempo limite de solicitação em segundos (padrão 120)
SGAI_API_KEY — chave da API (também pode ser passada via MCP scrapegraphApiKey ou cabeçalho X-API-Key)

Aliases legados (ainda aceitos): SCRAPEGRAPH_API_BASE_URL para SGAI_API_URL, SGAI_TIMEOUT_S para SGAI_TIMEOUT.

Principais Recursos

Raspar e extrair: scrape (POST /scrape, multi-formato), extract (POST /extract, URL + prompt)
Busca: search (POST /search; num_results limitado entre 3–20)
Crawl: Crawl assíncrono de múltiplas páginas com crawl_start / crawl_get_status / crawl_stop / crawl_resume
Schema: schema (POST /schema) — gera ou aumenta um JSON Schema a partir de um prompt
Monitores: Tarefas agendadas via monitor_create, monitor_list, monitor_get, pausar/retomar/excluir, monitor_activity (histórico de ticks paginado)
Conta: credits, history
Integração fácil: Claude Desktop, Cursor, Smithery, transporte HTTP
Documentação para desenvolvedores: pasta .agent/

Migração: v2 → v3

A v3 renomeia todas as ferramentas MCP que divergiam da documentação da API v2. Renomeação rígida, sem aliases.

v2 (antigo)	v3 (novo)
`smartscraper`	`extract`
`searchscraper`	`search`
`smartcrawler_initiate`	`crawl_start`
`smartcrawler_fetch_results`	`crawl_get_status`
`sgai_history`	`history`
`generate_schema`	`schema`
`markdownify`	removido — use `scrape` com `output_format="markdown"`

Início Rápido

1. Obtenha Sua Chave de API

Cadastre-se e obtenha sua chave de API no Painel do ScrapeGraph

2. Instale com Smithery (Recomendado)

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

3. Comece a Usar

Pergunte ao Claude ou Cursor:

"Converta https://scrapegraphai.com para markdown"
"Extraia todos os preços de produtos desta página de e-commerce"
"Pesquise os últimos desenvolvimentos em IA e resuma as descobertas"

É isso! O servidor agora está disponível para seu assistente de IA.

Ferramentas Disponíveis

Ferramenta	Função
`scrape`	POST /scrape (`output_format`: markdown, html, screenshot, branding, links, images, summary)
`extract`	POST /extract (requer `website_url` + `user_prompt`; opcional `output_schema`)
`search`	POST /search (`num_results` 1–20; suporta `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 (consulte até `status: completed`)
`crawl_stop`, `crawl_resume`	POST /crawl/:id/stop \| resume
`schema`	POST /schema (gera ou aumenta um JSON Schema a partir de um 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 (histórico de ticks paginado: `id`, `createdAt`, `status`, `changed`, `elapsedMs`, `diffs`)

Removidos: sitemap, agentic_scrapper, polling de status assíncrono e (na v3) markdownify — use scrape com output_format="markdown".

Instruções de Configuração

Para utilizar este servidor, você precisará de uma chave de API do ScrapeGraph. Siga estas etapas para obter uma:

Navegue até o Painel do ScrapeGraph
Crie uma conta e gere sua chave de API

Instalação Automatizada via Smithery

Para instalação automatizada do Servidor de Integração da API ScrapeGraph usando Smithery:

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

Configuração do Claude Desktop

Atualize o arquivo de configuração do Claude Desktop com as seguintes configurações (localizado no canto superior direito da página do Cursor):

(lembre-se de adicionar sua chave de API dentro da configuração)

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

O arquivo de configuração está localizado em:

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

Integração com Cursor

Adicione o servidor MCP do ScrapeGraphAI nas configurações:

Cursor MCP Integration

Uso do Servidor Remoto

Conecte-se ao nosso servidor MCP hospedado — sem necessidade de instalação local!

[!WARNING] O endpoint MCP legado em https://mcp.scrapegraphai.com/mcp será descontinuado em breve. Novas integrações devem usar o endpoint MCP substituto: https://sgai-mcp-main.onrender.com.

Configuração do Claude Desktop (Remoto)

Adicione isto à configuração do Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json no 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"
      ]
    }
  }
}

Configuração do Cursor (Remoto)

O Cursor suporta conexões MCP HTTP nativas. Adicione às configurações MCP do Cursor (~/.cursor/mcp.json):

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

Benefícios do Servidor Remoto

Sem configuração local - Basta configurar e começar a usar
Sempre atualizado - Recebe automaticamente as últimas atualizações
Multiplataforma - Funciona em qualquer sistema operacional com Node.js

Uso Local

Para executar o servidor MCP localmente para desenvolvimento ou testes, siga estas etapas:

Pré-requisitos

Python 3.13 ou superior
Gerenciador de pacotes pip ou uv
Chave de API do ScrapeGraph

Instalação

Clone o repositório (se ainda não o fez):

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

Instale o pacote:

# Using pip
pip install -e .

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

Defina sua chave 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

Executando o Servidor Localmente

Você pode executar o servidor diretamente:

# Using the installed command
scrapegraph-mcp

# Or using Python module
python -m scrapegraph_mcp.server

O servidor iniciará e se comunicará via stdio (entrada/saída padrão), que é o método de transporte MCP padrão.

Testando com o MCP Inspector

Teste seu servidor local usando a ferramenta MCP Inspector:

npx @modelcontextprotocol/inspector python -m scrapegraph_mcp.server

Isso fornece uma interface web para testar todas as ferramentas disponíveis interativamente.

Configurando o Claude Desktop para o Servidor Local

Para usar seu servidor em execução local com o Claude Desktop, atualize seu arquivo de configuração:

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: Certifique-se de que o Python esteja no seu PATH. Você pode verificar executando python --version no seu terminal.

Configurando o Cursor para o Servidor Local

Nas configurações MCP do Cursor, adicione um novo servidor com:

Comando: python
Argumentos: ["-m", "scrapegraph_mcp.server"]
Variáveis de Ambiente: {"SGAI_API_KEY": "your-api-key-here"}

Solução de Problemas na Configuração Local

Servidor não iniciando:

Verifique se o Python está instalado: python --version
Verifique se o pacote está instalado: pip list | grep scrapegraph-mcp
Garanta que a chave de API esteja definida: echo $SGAI_API_KEY (macOS/Linux) ou echo %SGAI_API_KEY% (Windows)

Ferramentas não aparecendo:

Verifique os logs do Claude Desktop:
- macOS: ~/Library/Logs/Claude/
- Windows: %APPDATA%\Claude\Logs\
Verifique se o servidor inicia sem erros quando executado diretamente
Verifique se o JSON de configuração é válido

Erros de importação:

Reinstale o pacote: pip install -e . --force-reinstall
Verifique as dependências: pip install -r requirements.txt (se disponível)

Integração com Google ADK

O servidor MCP do ScrapeGraph pode ser integrado ao Google ADK (Agent Development Kit) para criar agentes de IA com recursos de raspagem web.

Pré-requisitos

Python 3.13 ou superior
Google ADK instalado
Chave de API do ScrapeGraph

Instalação

Instale o Google ADK (se ainda não estiver instalado):

pip install google-adk

Defina sua chave de API:

export SGAI_API_KEY=your-api-key-here

Exemplo Básico de Integração

Crie um arquivo de agente (ex.: agent.py) com a seguinte configuração:

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

Opções de Configuração

Configurações de Tempo Limite:

O tempo limite padrão é de 5 segundos, o que pode ser curto demais para operações de raspagem web
Recomendado: Defina `timeout=300.0
Ajuste com base no seu caso de uso (operações de crawl podem precisar de tempos ainda maiores)

Filtragem de Ferramentas:

Por padrão, todas as ferramentas MCP registradas são expostas ao agente (veja Ferramentas Disponíveis)
Use tool_filter para limitar quais ferramentas estão disponíveis:
```
tool_filter=['scrape', 'extract', 'search']
```

Configuração da Chave de API:

Defina via variável de ambiente: export SGAI_API_KEY=your-key
Ou passe diretamente no dicionário env: 'SGAI_API_KEY': 'your-key-here'
A abordagem com variável de ambiente é recomendada por segurança

Exemplo de Uso

Uma vez configurado, seu agente pode usar linguagem natural para interagir com as ferramentas de raspagem web:

# 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 mais informações sobre o Google ADK, visite a documentação oficial.

Exemplos de Casos de Uso

O servidor permite consultas sofisticadas em vários cenários de raspagem:

Raspagem de Página Única

Markdownify: "Converta a página de documentação do ScrapeGraph para markdown"
Extract: "Extraia todos os nomes de produtos, preços e avaliações desta página de e-commerce"
Extract com rolagem: "Raspe esta página de rolagem infinita com 5 rolagens e extraia todos os itens"
Basic Scrape: "Busque o conteúdo HTML desta página com muito JavaScript com renderização completa"

Busca e Pesquisa

Search: "Pesquise e resuma os desenvolvimentos recentes em raspagem web com IA"
Search: "Busque os 5 principais artigos sobre frameworks de aprendizado de máquina e extraia insights-chave"
Search: "Encontre notícias recentes sobre GPT-4 e forneça um resumo estruturado"
Search: a v2 não aplica time_range; formule consultas para favorecer a recência em linguagem natural

Análise de Sites

Use crawl_start junto com crawl_get_status para mapear e capturar conteúdo de múltiplas páginas; não há uma ferramenta separada de sitemap na v2.

Crawl de Múltiplas Páginas

Crawl: "Raspe o blog em modo markdown e consulte até concluir"
Para campos estruturados por página, execute extract em URLs individuais (ou monitor_create em um agendamento)

Monitores e Conta

Monitor: "Execute este prompt de extração em https://example.com todos os dias às 9h" (monitor_create com intervalo)
Créditos / histórico: credits, history
Raspador Agêntico: "Execute um fluxo de trabalho complexo: faça login, navegue até os relatórios, baixe os dados e extraia estatísticas resumidas"

Tratamento de Erros

O servidor implementa tratamento robusto de erros com mensagens detalhadas e acionáveis para:

Problemas de autenticação na API
Estruturas de URL malformadas
Falhas de conectividade de rede
Limitação de taxa e gerenciamento de cota

Problemas Comuns

Conexão Específica do Windows

Ao executar em sistemas Windows, você pode precisar usar o seguinte comando para conectar ao servidor MCP:

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

Isso garante a execução adequada no ambiente Windows.

Outros Problemas Comuns

"Cliente ScrapeGraph não inicializado"

Causa: Chave de API ausente
Solução: Defina a variável de ambiente SGAI_API_KEY ou forneça via --config

"Erro 401: Não autorizado"

Causa: Chave de API inválida
Solução: Verifique sua chave de API no Painel do ScrapeGraph "Erro 402: Pagamento Necessário"
Causa: Créditos insuficientes
Solução: Adicione créditos à sua conta ScrapeGraph

Crawl não retornando resultados

Causa: Ainda processando (operação assíncrona)
Solução: Continue consultando crawl_get_status() até que o status seja "concluído"

Ferramentas não aparecendo no Claude Desktop

Causa: Servidor não iniciando ou erro de configuração
Solução: Verifique os logs do Claude em ~/Library/Logs/Claude/ (macOS) ou %APPDATA%\Claude\Logs\ (Windows)

Para solução de problemas detalhada, consulte a documentação .agent.

Desenvolvimento

Pré-requisitos

Python 3.13 ou superior
Gerenciador de pacotes pip ou uv
Chave da API ScrapeGraph

Instalação a partir do código-fonte

# 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

Testando com o MCP Inspector

Teste seu servidor localmente usando a ferramenta MCP Inspector:

npx @modelcontextprotocol/inspector scrapegraph-mcp

Isso fornece uma interface web para testar todas as ferramentas disponíveis.

Qualidade do código

Linting:

ruff check src/

Verificação de tipos:

mypy src/

Verificação de formatação:

ruff format --check src/

Estrutura do projeto

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

Contribuindo

Aceitamos contribuições! Veja como você pode ajudar:

Adicionando uma nova ferramenta

Adicione o método à classe ScapeGraphClient em 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()

Adicione o decorador de ferramenta 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)}

Teste com o MCP Inspector:

npx @modelcontextprotocol/inspector scrapegraph-mcp

Atualize a documentação:
- Adicione a ferramenta a este README
- Atualize a documentação .agent
Envie um pull request

Fluxo de trabalho de desenvolvimento

Faça um fork do repositório
Crie um branch de funcionalidade (git checkout -b feature/amazing-feature)
Faça suas alterações
Execute linting e verificação de tipos
Teste com o MCP Inspector e o Claude Desktop
Atualize a documentação
Faça commit das suas alterações (git commit -m 'Add amazing feature')
Envie para o branch (git push origin feature/amazing-feature)
Abra um Pull Request

Estilo de código

Comprimento de linha: 100 caracteres
Anotações de tipo: Obrigatórias para todas as funções
Docstrings: Docstrings no estilo Google
Tratamento de erros: Retorne dicionários de erro, não levante exceções nas ferramentas
Versão do Python: Alvo 3.13+

Para diretrizes detalhadas de desenvolvimento, consulte a documentação .agent.

Documentação

Para documentação abrangente para desenvolvedores, consulte:

.agent/README.md - Índice completo da documentação para desenvolvedores
.agent/system/project_architecture.md - Arquitetura do sistema e design
.agent/system/mcp_protocol.md - Detalhes da integração do protocolo MCP

Pilha de tecnologia

Estrutura principal

Python 3.13+ - Python moderno com anotações de tipo
FastMCP - Estrutura leve de servidor MCP
httpx 0.24.0+ - Cliente HTTP assíncrono moderno

Ferramentas de desenvolvimento

Ruff - Linter e formatador Python rápido
mypy - Verificador de tipos estático
Hatchling - Backend de build moderno

Implantação

Smithery - Implantação automatizada de servidor MCP
Docker - Suporte a contêineres com Alpine Linux
transporte stdio - Comunicação MCP padrão

Integração de API

API ScrapeGraph AI - Serviço empresarial de web scraping
URL base: https://v2-api.scrapegraphai.com/api
Autenticação: baseada em chave de API

Licença

Este projeto é distribuído sob a Licença MIT. Para termos e condições detalhados, consulte o arquivo LICENSE.

Agradecimentos

Agradecimentos especiais a tomekkorbak pela implementação de oura-mcp-server, que serviu como ponto de partida para este repositório.

Recursos

Links oficiais

Página inicial do ScrapeGraph AI
Painel do ScrapeGraph - Obtenha sua chave de API
Documentação da API ScrapeGraph
Repositório GitHub

Recursos MCP

Model Context Protocol - Especificação oficial do MCP
Estrutura FastMCP - Estrutura usada por este servidor
MCP Inspector - Ferramenta de teste
Smithery - Distribuição de servidor MCP
mcp-name: io.github.ScrapeGraphAI/scrapegraph-mcp

Integração com assistentes de IA

Claude Desktop - Aplicativo desktop com suporte a MCP
Cursor - Editor de código com IA

Suporte

Issues do GitHub - Relate bugs ou solicite recursos
Documentação para desenvolvedores - Documentação abrangente para desenvolvedores

Feito com ❤️ pela equipe ScrapeGraphAI