Outscraper

Servidor MCP da Outscraper

Um servidor Model Context Protocol (MCP) simplificado que fornece acesso aos serviços de extração de dados do Google Maps da Outscraper. Este servidor implementa 2 ferramentas essenciais para extrair dados do Google Maps com alta confiabilidade.

🚀 Recursos

Extração de Dados do Google Maps

• 🗺️ Pesquisa no Google Maps - Pesquise empresas e lugares com informações detalhadas
• ⭐ Avaliações do Google Maps - Extraia avaliações de clientes de qualquer lugar do Google Maps

Recursos Avançados

• Enriquecimento de Dados - Aprimore os resultados com informações de contato adicionais via parâmetro de enriquecimento
• Suporte a Múltiplos Idiomas - Pesquise e extraia dados em diferentes idiomas
• Filtragem Regional - Direcione países/regiões específicos para resultados localizados
• Ordenação Flexível - Ordene avaliações por relevância, data, classificação, etc.
• Filtragem por Tempo - Filtre avaliações por data usando o parâmetro de corte
• Suporte a Alto Volume - Processa assincronamente solicitações grandes automaticamente

📦 Instalação

Instalação via Smithery (Recomendado)

Para instalar o servidor MCP da Outscraper para o Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install outscraper-mcp --client claude

Instalação via PyPI

# Using pip
pip install outscraper-mcp

# Using uv (recommended)
uv add outscraper-mcp

# Using uvx for one-time execution
uvx outscraper-mcp

Instalação Manual

git clone https://github.com/jayozer/outscraper-mcp
cd outscraper-mcp

# Using uv (recommended)
uv sync

# Using pip
pip install -e .

🔧 Configuração

Obtenha Sua Chave de API

1. Cadastre-se em Outscraper
2. Obtenha sua chave de API na página de perfil

Defina a Variável de Ambiente

export OUTSCRAPER_API_KEY="your_api_key_here"

Ou crie um arquivo .env:

OUTSCRAPER_API_KEY=your_api_key_here

🛠️ Configuração do Cliente

Claude Desktop

Adicione ao seu claude_desktop_config.json:

Via Smithery (Automático):

{
  "mcpServers": {
    "outscraper": {
      "command": "npx",
      "args": ["-y", "@smithery/cli", "run", "outscraper-mcp"],
      "env": {
        "OUTSCRAPER_API_KEY": "your_api_key_here"
      }
    }
  }
}

Via Instalação Local:

{
  "mcpServers": {
    "outscraper": {
      "command": "uvx",
      "args": ["outscraper-mcp"],
      "env": {
        "OUTSCRAPER_API_KEY": "your_api_key_here"
      }
    }
  }
}

Via Instalação Manual:

{
  "mcpServers": {
    "outscraper": {
      "command": "uv",
      "args": ["run", "python", "-m", "outscraper_mcp"],
      "env": {
        "OUTSCRAPER_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cursor AI

Instalação Automática com UVX (Recomendado):

{
  "mcpServers": {
    "outscraper": {
      "command": "uvx",
      "args": ["outscraper-mcp"],
      "env": {
        "OUTSCRAPER_API_KEY": "your_api_key_here"
      }
    }
  }
}

Instalação Manual:

{
  "mcpServers": {
    "outscraper": {
      "command": "outscraper-mcp",
      "env": {
        "OUTSCRAPER_API_KEY": "your_api_key_here"
      }
    }
  }
}

Nota para Usuários do Cursor: O arquivo de configuração normalmente está localizado em:

• macOS: ~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Windows: %APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
• Linux: ~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

🛠️ Referência de Ferramentas

google_maps_search

Pesquise empresas e lugares no Google Maps

# Parameters:
query: str              # Search query (e.g., 'restaurants brooklyn usa')
limit: int = 20         # Number of results (max: 400)
language: str = "en"    # Language code
region: str = None      # Country/region code (e.g., 'US', 'GB')
drop_duplicates: bool = False  # Remove duplicate results
enrichment: List[str] = None   # Additional services ['domains_service', 'emails_validator_service']

google_maps_reviews

Extraia avaliações de lugares do Google Maps

# Parameters:
query: str              # Place query, place ID, or business name
reviews_limit: int = 10 # Number of reviews per place (0 for unlimited)
limit: int = 1          # Number of places to process
sort: str = "most_relevant"  # Sort order: 'most_relevant', 'newest', 'highest_rating', 'lowest_rating'
language: str = "en"    # Language code
region: str = None      # Country/region code
cutoff: int = None      # Unix timestamp for reviews after specific date

🚀 Executando o Servidor

Desenvolvimento e Testes

# FastMCP Inspector - Web-based testing dashboard
fastmcp dev outscraper_mcp/server.py

# Then open your browser to: http://127.0.0.1:6274
# Interactive testing of Google Maps tools with real-time responses

Transporte Stdio (Padrão)

# Via PyPI installation
outscraper-mcp

# Via uv
uv run python -m outscraper_mcp

# Via manual installation
python -m outscraper_mcp

Transporte HTTP

from outscraper_mcp import mcp

if __name__ == "__main__":
    mcp.run(transport="streamable-http", host="127.0.0.1", port=8000)

💡 Exemplos de Uso

Exemplo 1: Encontre Restaurantes e Obtenha Avaliações

# 1. Search for restaurants
results = google_maps_search(
    query="italian restaurants manhattan nyc",
    limit=5,
    language="en",
    region="US"
)

# 2. Get reviews for a specific place
reviews = google_maps_reviews(
    query="ChIJrc9T9fpYwokRdvjYRHT8nI4",  # Place ID from search results
    reviews_limit=20,
    sort="newest"
)

Exemplo 2: Geração de Leads com Enriquecimento

# Find businesses with enhanced contact information
businesses = google_maps_search(
    query="digital marketing agencies chicago",
    limit=20,
    enrichment=["domains_service", "emails_validator_service"]
)

# Get detailed reviews for sentiment analysis
for business in businesses:
    if business.get('place_id'):
        reviews = google_maps_reviews(
            query=business['place_id'],
            reviews_limit=10,
            sort="newest"
        )

Exemplo 3: Pesquisa de Mercado

# Research competitors in specific area
competitors = google_maps_search(
    query="coffee shops downtown portland",
    limit=50,
    region="US"
)

# Analyze recent customer feedback
recent_reviews = google_maps_reviews(
    query="coffee shops downtown portland",
    reviews_limit=100,
    sort="newest"
)

🔄 Integração com Clientes MCP

Este servidor é compatível com qualquer cliente MCP, incluindo:

• Claude Desktop
• Cursor AI
• Raycast
• VS Code com extensões MCP
• Clientes MCP personalizados

📊 Limites de Taxa e Preços

• Consulte Preços da Outscraper para tarifas atuais
• O uso da chave de API é rastreado por solicitação
• Considere implementar cache para dados acessados com frequência

🐛 Solução de Problemas

Problemas Comuns

1. Erro de Importação: Certifique-se de que instalou o pacote corretamente

   pip install --upgrade outscraper-mcp
   

2. Erro de Chave de API: Verifique se sua chave de API está definida corretamente

   echo $OUTSCRAPER_API_KEY
   

3. Sem Resultados: Verifique se seus parâmetros de consulta são válidos

4. Limites de Taxa: Implemente atrasos entre solicitações, se necessário

Ativar Registro de Depuração

import logging
logging.basicConfig(level=logging.DEBUG)

🤝 Contribuindo

1. Faça um fork do repositório
2. Crie um branch de funcionalidade
3. Faça suas alterações
4. Adicione testes
5. Envie um pull request

📄 Licença

Licença de Software Experimental - consulte o arquivo LICENSE para detalhes.

Aviso: Este software é experimental e gratuito para todos os fins. Criado por Jay Ozer.

🔗 Links

• Documentação da API Outscraper
• Documentação do FastMCP
• Model Context Protocol
• Registro Smithery

---

Construído com Blu Goldens