Outscraper MCP Server

Outscraper MCP

Servidor MCP oficial para Outscraper.

Conecte agentes de IA ao Outscraper para descoberta de negócios, inteligência do Google Maps, enriquecimento de empresas e contatos, análise de avaliações, pesquisa e extração estruturada da web.

Melhor Para

• prospecção de negócios locais e geração de leads
• inteligência de lugares, fotos e avaliações do Google Maps
• enriquecimento de empresas e contatos a partir de domínios conhecidos
• fluxos de trabalho assíncronos de coleta de dados com polling
• extração de informações estruturadas de uma única página

Não Ideal Para

• automação de navegador ou interação de UI em várias etapas
• integrações SaaS genéricas baseadas em OAuth
• busca arbitrária de documentos fora da superfície de dados do Outscraper
• sessões de rastreamento de sites que exigem um navegador persistente

Fluxos de Trabalho Comuns

• encontre negócios com businesses_search, depois enriqueça um registro escolhido com businesses_get
• pesquise lugares no Google Maps e depois busque avaliações ou fotos para análise de reputação
• enriqueça um domínio de empresa, valide e-mails e verifique a cobertura de contatos
• envie trabalhos assíncronos e depois faça polling com requests_get
• extraia dados estruturados de uma página com ai_scraper

Ele expõe ferramentas MCP prontas para produção para:

• descoberta e enriquecimento de negócios
• lugares, avaliações, fotos e detecção de cadeias do Google Maps
• insights de empresas, e-mails, validação de e-mail e enriquecimento de telefones
• Pesquisa Google e pesquisa de Imagens Google
• dados de Yellow Pages, Booking, Yelp, Tripadvisor, Trustpilot e Indeed
• verificações de saldo da conta e gerenciamento do ciclo de vida de solicitações assíncronas

O servidor suporta transportes stdio e HTTP, instalação baseada em npm, autenticação hospedada por cabeçalho ou URL e um formato de resultado normalizado structuredContent para clientes e agentes MCP.

O Que Ele Faz

Este servidor MCP expõe fontes de dados e fluxos de trabalho de enriquecimento do Outscraper para clientes compatíveis com MCP.

Ele foi projetado para:

• descoberta de negócios e lugares
• recuperação de avaliações e fotos do Google Maps
• enriquecimento de contatos e empresas
• extração estruturada assistida por IA de uma única página com ai_scraper
• envio de solicitações assíncronas e polling por meio de requests_get

Na prática, o servidor atua como uma camada MCP fina sobre a API do Outscraper:

• clientes MCP chamam ferramentas neste servidor
• o servidor autentica com uma chave de API do Outscraper
• as solicitações são encaminhadas para endpoints do Outscraper
• os resultados são retornados em um envelope de ferramenta MCP normalizado

Início Rápido

set OUTSCRAPER_API_KEY=YOUR_API_KEY
npx -y outscraper-mcp

Para clientes MCP, configure:

• comando: npx
• argumentos: ["-y", "outscraper-mcp"]
• env: OUTSCRAPER_API_KEY=YOUR_API_KEY

Para fluxos de trabalho orientados a tarefas, exemplos de copiar e colar e habilidades de agente de exemplo, consulte a pasta examples.

Ferramentas Atuais

• ping
• businesses_search
• businesses_get
• ai_scraper
• google_maps_search
• google_maps_reviews
• company_insights
• emails_and_contacts
• emails_validator
• google_maps_photos
• chain_info
• yellowpages_search
• booking_reviews
• phones_enricher
• tp_data (alias legado para trustpilot_data)
• trustpilot_data
• tp_reviews (alias legado para trustpilot_reviews)
• trustpilot_reviews
• yelp_reviews
• tripadvisor_search
• tripadvisor_reviews
• google_search
• google_search_images
• indeed_search
• balance_get
• requests_get
• requests_list
• requests_delete

Essas ferramentas estão alinhadas aos formatos atuais documentados da API do Outscraper, incluindo:

• POST /businesses
• POST /ai-scraper
• GET /businesses/{business_id}
• GET /google-maps-search
• GET /google-maps-photos
• GET /google-search
• GET /google-search-images
• GET /yellowpages-search
• GET /booking-reviews
• GET /phones-enricher
• GET /trustpilot
• GET /trustpilot-reviews
• GET /yelp-reviews
• GET /tripadvisor-search
• GET /tripadvisor-reviews
• GET /indeed-search
• GET /google-maps-reviews
• GET /company-insights
• GET /emails-and-contacts
• GET /email-validator
• enriquecimento documentado de ai_chain_info via google-maps-search
• GET /profile/balance
• GET /requests/{requestId}
• DELETE /requests/{requestId}
• GET /requests

Formato Unificado de Resultado de Ferramenta

Toda ferramenta agora retorna o mesmo envelope estruturado:

{
  "data": {},
  "meta": {
    "service": "company_insights",
    "operation": "get"
  },
  "async": {
    "id": "request-id",
    "status": "Pending",
    "results_location": "https://api.outscraper.com/requests/request-id",
    "is_async_submission": true,
    "next_step": "Call requests_get with request_id=\"request-id\" to check progress."
  }
}

async está presente quando a resposta é um envio assíncrono ou expõe metadados de solicitação assíncrona.

Modo de Execução

Ferramentas com capacidade assíncrona agora aceitam:

{
  "execution_mode": "auto"
}

Valores disponíveis:

• auto: deixe o servidor MCP escolher síncrono ou assíncrono
• sync: forçar modo de resposta direta
• async: forçar modo de envio assíncrono

O antigo booleano async ainda é aceito para compatibilidade, mas execution_mode agora tem prioridade.

Instalação

A maneira recomendada de usar este servidor MCP é via npm.

Executar a partir do npm

npx -y outscraper-mcp

Forneça OUTSCRAPER_API_KEY por meio da configuração do seu cliente MCP ou do ambiente de shell.

O servidor carrega automaticamente .env na inicialização via dotenv.

No Windows, se um cliente não conseguir encontrar npx, use o caminho completo do Node.js, por exemplo:

{
  "command": "C:\\Program Files\\nodejs\\npx.cmd",
  "args": ["-y", "outscraper-mcp"]
}

Segurança

Problemas sensíveis à segurança devem ser relatados de acordo com SECURITY.md.

Modos de Conexão

O servidor atualmente suporta estes padrões de conexão:

1. MCP stdio local

Melhor para:

• Claude Desktop
• Claude Code
• Cursor
• VS Code
• Windsurf
• desenvolvimento MCP local

Fonte de autenticação:

• variável de ambiente OUTSCRAPER_API_KEY

Transporte:

• processo local via stdio

2. HTTP Streamable sem estado remoto

Melhor para:

• endpoints MCP hospedados
• n8n
• proxy reverso ou implantação baseada em domínio
• uso remoto em contêineres

Fonte de autenticação quando CLOUD_SERVICE=true:

• X-OUTSCRAPER-API-KEY
• X-API-KEY
• Authorization: Bearer <api-key>
• autenticação por caminho /v1/mcp/<api-key>

Transporte:

• HTTP POST /mcp
• HTTP POST /v1/mcp/<api-key>

3. HTTP/SSE com estado remoto

Melhor para:

• uso MCP baseado em sessão
• clientes que dependem da semântica de transporte HTTP com estado

Fonte de autenticação quando CLOUD_SERVICE=true:

• as mesmas opções de autenticação por cabeçalho ou URL do HTTP sem estado

Transporte:

• POST /mcp
• GET /mcp
• DELETE /mcp
• e o mesmo padrão de rota /v1/mcp/<api-key>

Nota:

• o modo com estado armazena sessões na memória do processo, portanto é mais adequado para uma única instância ou implantação com sessão fixa do que para escalonamento horizontal

Conector ChatGPT

Se você quiser conectar este servidor ao ChatGPT como um conector MCP remoto, a forma hospedada mais simples é:

https://your-domain.example/v1/mcp/YOUR_API_KEY

Configuração recomendada:

1. Implante o servidor via HTTPS atrás de um domínio real ou proxy reverso.
2. Ative o modo hospedado com CLOUD_SERVICE=true.
3. Use a rota de autenticação por URL se o conector não puder anexar cabeçalhos de autenticação personalizados.
4. Prefira autenticação por cabeçalho para clientes servidor a servidor quando cabeçalhos personalizados estiverem disponíveis.

Valores típicos do conector:

• Nome: Outscraper MCP
• Descrição: Business discovery, Google Maps data, enrichment, search, and AI scraping
• URL do servidor MCP: https://your-domain.example/v1/mcp/YOUR_API_KEY
• Autenticação: None

Notas:

• A autenticação por URL é a opção mais conveniente para configuração estilo conector, mas é menos privada que a autenticação por cabeçalho porque URLs têm maior probabilidade de aparecer em logs.
• Evite túneis temporários que injetam páginas de aviso do navegador, a menos que seu conector possa ignorá-los de forma limpa.

Modo de Autenticação por Cabeçalho Hospedado

Se você quiser comportamento hospedado, ative:

set CLOUD_SERVICE=true

Então o chamador HTTP pode enviar a chave de API do Outscraper em um destes cabeçalhos:

• Authorization: Bearer <api-key>
• X-API-KEY: <api-key>
• X-OUTSCRAPER-API-KEY: <api-key>

No modo HTTP CLOUD_SERVICE=true, os cabeçalhos da solicitação são usados como fonte da chave de API. No modo stdio local, OUTSCRAPER_API_KEY ainda é necessário.

Solicitações HTTP sem uma dessas formas de autenticação são rejeitadas antes do início do processamento MCP.

Modo de Autenticação por URL Hospedado

Para conectores estilo ChatGPT ou outras configurações hospedadas que não podem enviar cabeçalhos personalizados, você também pode passar a chave de API no caminho:

http://localhost:3000/v1/mcp/YOUR_API_KEY

Esta rota suporta o mesmo comportamento MCP que /mcp, mas autentica a partir do caminho da URL quando CLOUD_SERVICE=true.

Para integrações servidor a servidor, a autenticação por cabeçalho ainda é preferida porque chaves de API baseadas em URL têm maior probabilidade de aparecer em logs.

Executar com HTTP Streamable

set HTTP_STREAMABLE_SERVER=true
set HOST=localhost
set PORT=3000
npx -y outscraper-mcp

Endpoint MCP:

http://localhost:3000/mcp

Endpoint de autenticação por URL hospedado:

http://localhost:3000/v1/mcp/YOUR_API_KEY

Endpoint de saúde:

http://localhost:3000/health

Executar com Docker Compose

Este repositório também inclui um docker-compose.yml para implantações hospedadas/em contêineres:

docker compose up --build -d

Comportamento padrão do contêiner:

• vincula 3000:3000
• ativa CLOUD_SERVICE=true
• ativa HTTP Streamable sem estado
• escuta em 0.0.0.0
• usa https://api.outscraper.com como URL base da API upstream

Endpoints:

http://localhost:3000/mcp
http://localhost:3000/v1/mcp/YOUR_API_KEY
http://localhost:3000/health

Notas importantes para uso com Docker:

• este arquivo compose é destinado a acesso remoto hospedado, não a clientes stdio locais
• por padrão, espera que os chamadores autentiquem por solicitação, não por uma única chave de API para todo o servidor
• se você colocar o serviço atrás de um domínio ou proxy reverso, prefira autenticação por cabeçalho para uso servidor a servidor
• a autenticação por URL está disponível principalmente para fluxos de conector que não podem anexar cabeçalhos personalizados

Executar com Modo HTTP/SSE com Estado

Este modo usa gerenciamento de sessão local:

set SSE_LOCAL=true
set HOST=localhost
set PORT=3000
npx -y outscraper-mcp

Você também pode ativar o mesmo modo com:

set HTTP_STATEFUL_SERVER=true
set HOST=localhost
set PORT=3000
npx -y outscraper-mcp

Neste modo, o servidor aceita:

• POST /mcp para inicialização e solicitações subsequentes
• GET /mcp para o fluxo da sessão
• DELETE /mcp para encerramento da sessão

A sessão é rastreada por meio do cabeçalho mcp-session-id.

A autenticação por URL hospedada também funciona no modo com estado por meio de:

http://localhost:3000/v1/mcp/YOUR_API_KEY

Configuração do Cliente

{
  "mcpServers": {
    "outscraper": {
      "command": "npx",
      "args": ["-y", "outscraper-mcp"],
      "env": {
        "OUTSCRAPER_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

claude mcp add outscraper -e OUTSCRAPER_API_KEY=YOUR_API_KEY -- npx -y outscraper-mcp

{
  "mcpServers": {
    "outscraper": {
      "command": "npx",
      "args": ["-y", "outscraper-mcp"],
      "env": {
        "OUTSCRAPER_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "outscraper": {
      "command": "npx",
      "args": ["-y", "outscraper-mcp"],
      "env": {
        "OUTSCRAPER_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "outscraperApiKey",
        "description": "Outscraper API Key",
        "password": true
      }
    ],
    "servers": {
      "outscraper": {
        "command": "npx",
        "args": ["-y", "outscraper-mcp"],
        "env": {
          "OUTSCRAPER_API_KEY": "${input:outscraperApiKey}"
        }
      }
    }
  }
}

{
  "mcpServers": {
    "outscraper": {
      "command": "npx",
      "args": ["-y", "outscraper-mcp"],
      "env": {
        "OUTSCRAPER_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

set HTTP_STREAMABLE_SERVER=true
set HOST=localhost
set PORT=3000
set OUTSCRAPER_API_KEY=YOUR_API_KEY
npx -y outscraper-mcp

http://localhost:3000/mcp

Exemplos de Ferramentas

Pesquisar negócios com filtros estruturados

{
  "filters": {
    "country_code": "US",
    "states": ["NY"],
    "cities": ["New York"],
    "types": ["restaurant", "cafe"]
  },
  "fields": ["name", "phone", "website", "address", "rating", "reviews"],
  "limit": 25
}

O suporte a query em linguagem natural em /businesses atualmente depende do comportamento do próprio parser do Outscraper. Em testes ao vivo, filters estruturados foram confiáveis, enquanto valores de query de forma livre frequentemente retornavam Could not parse query into a valid request format.

Extrair dados estruturados com AI Scraper

{
  "query": "https://outscraper.com",
  "prompt": "Extract company name, company description, and people mentioned on the page.",
  "schema": {
    "type": "object",
    "required": [],
    "properties": {
      "company_name": { "type": "string" },
      "company_description": { "type": "string" },
      "people": {
        "type": "array",
        "items": { "type": "string" }
      }
    }
  },
  "execution_mode": "sync"
}

Use execution_mode: "async" se você quiser um ID de solicitação e planejar fazer polling mais tarde com requests_get.

Obter um negócio

{
  "business_id": "YOUR_BUSINESS_ID",
  "fields": ["name", "phone", "website", "address", "rating", "reviews"]
}

Pesquisar no Google Maps

{
  "query": ["restaurants brooklyn usa"],
  "limit": 20,
  "language": "en",
  "region": "us"
}

Buscar avaliações do Google Maps

{
  "query": ["ChIJrc9T9fpYwokRdvjYRHT8nI4"],
  "reviews_limit": 20,
  "sort": "newest",
  "language": "en"
}

Obter insights de empresas

{
  "query": ["outscraper.com"],
  "fields": ["name", "description", "industry"],
  "execution_mode": "async"
}

Encontrar e-mails e contatos

{
  "query": ["outscraper.com"],
  "preferred_contacts": ["technical", "decision makers"],
  "execution_mode": "sync"
}

Validar endereços de e-mail

{
  "query": ["support@outscraper.com"],
  "execution_mode": "sync"
}

Buscar fotos do Google Maps

{
  "query": ["NoMad Restaurant, NY, USA"],
  "photos_limit": 5,
  "limit": 1,
  "execution_mode": "sync"
}

Obter informações de cadeia

{
  "query": ["Starbucks, New York, NY, USA"],
  "limit": 1,
  "execution_mode": "sync"
}

Obter dados de negócios do Trustpilot

{
  "query": ["outscraper.com"],
  "execution_mode": "sync"
}

Pesquisar no Google

{
  "query": ["outscraper"],
  "pages_per_query": 1,
  "execution_mode": "sync"
}

Pesquisar no Google Imagens

{
  "query": ["outscraper"],
  "limit": 5,
  "execution_mode": "sync"
}

Pesquisar no Indeed

{
  "query": ["https://www.indeed.com/jobs?q=software+engineer&l=New+York%2C+NY"],
  "limit": 10,
  "execution_mode": "sync"
}

Verificar saldo da conta

{}

Excluir solicitação assíncrona

{
  "request_id": "YOUR_REQUEST_ID"
}

Limitações Conhecidas

• businesses_search funciona de forma confiável com filters estruturados, mas valores de query de formato livre em /businesses podem falhar com Could not parse query into a valid request format. Esse comportamento foi reproduzido contra a API ao vivo, não apenas dentro da camada MCP.
• ai_scraper funciona melhor através de POST com corpo JSON. Na validação ao vivo, POST aceitou prompt e schema de forma confiável, enquanto variantes de GET em torno de schema e query_schema não corresponderam ao mesmo comportamento de forma consistente.
• Quando os exemplos do OpenAPI do Outscraper e o comportamento da API ao vivo diferem, o comportamento do endpoint ao vivo deve ser tratado como a fonte da verdade.
• businesses_search é intencionalmente exposto aqui como uma ferramenta MCP síncrona porque o formato OpenAPI atual de /businesses é baseado em corpo de requisição e não se mostrou um fluxo de trabalho estável no estilo assíncrono durante a validação ao vivo.
• execution_mode="auto" é orientado por heurística. Ele foi projetado para escolher um padrão prático, mas chamadores que precisam de comportamento determinístico devem usar explicitamente sync ou async.
• O modo hospedado HTTP requer cabeçalhos de autenticação corretos quando CLOUD_SERVICE=true; o modo stdio ainda espera OUTSCRAPER_API_KEY no ambiente do processo.
• chain_info é implementado a partir do enriquecimento documentado de ai_chain_info em google-maps-search, porque o Outscraper atualmente não descreve um endpoint independente de chain info.
• builtwith não é atualmente exposto como uma ferramenta porque o Outscraper atualmente não documenta um endpoint dedicado do BuiltWith.

Notas de Seleção de Ferramentas

• Use businesses_search para descoberta estruturada de negócios com filtros e paginação por cursor.
• Use businesses_get quando você já tiver um ID de negócio concreto.
• Use google_maps_search para descoberta de lugares no estilo Google Maps a partir de consultas de pesquisa humanas.
• Use google_maps_reviews quando o usuário precisar especificamente de dados de avaliações em vez de descoberta de lugares.
• Use company_insights para firmografia e enriquecimento de perfil de empresas.
• Use emails_and_contacts para descoberta de contatos a partir de domínios conhecidos.
• Use requests_get, requests_list e requests_delete apenas para gerenciamento do ciclo de vida assíncrono.
• Use balance_get para verificações de conta e cobrança, não para recuperação de dados de negócios.

Notas

• O servidor suporta stdio, HTTP Streamable sem estado e modo local HTTP/SSE com estado.
• CLOUD_SERVICE=true permite a resolução de chave de API baseada em cabeçalho para requisições HTTP.
• Para publicação no npm, o conteúdo do pacote é intencionalmente limitado a artefatos de runtime e documentação.
• Os trechos de configuração específicos de clientes neste README são destinados a servir como modelos práticos; a interface exata de configurações e os nomes das chaves de configuração podem variar ligeiramente entre clientes e versões do MCP.