Outscraper MCP Server

Outscraper MCP

Servidor MCP oficial para Outscraper.

Conecta agentes de IA a Outscraper para descubrimiento de negocios, inteligencia de Google Maps, enriquecimiento de empresas y contactos, análisis de reseñas, búsqueda y extracción web estructurada.

Ideal para

• prospección de negocios locales y generación de leads
• inteligencia de lugares, fotos y reseñas de Google Maps
• enriquecimiento de empresas y contactos a partir de dominios conocidos
• flujos de trabajo de recopilación de datos asíncronos con sondeo
• extracción de información estructurada de una sola página

No es ideal para

• automatización de navegador o interacción de UI en varios pasos
• integraciones SaaS genéricas basadas en OAuth
• búsqueda arbitraria de documentos fuera de la superficie de datos de Outscraper
• sesiones de rastreo web que requieren un navegador persistente

Flujos de trabajo comunes

• encuentra negocios con businesses_search, luego enriquece un registro elegido con businesses_get
• busca lugares en Google Maps, luego obtén reseñas o fotos para análisis de reputación
• enriquece un dominio de empresa, valida correos electrónicos y verifica la cobertura de contactos
• envía trabajos asíncronos y luego hazles sondeo con requests_get
• extrae datos estructurados de una página con ai_scraper

Expone herramientas MCP listas para producción para:

• descubrimiento y enriquecimiento de negocios
• lugares, reseñas, fotos y detección de cadenas de Google Maps
• información de empresas, correos electrónicos, validación de correos y enriquecimiento de teléfonos
• búsqueda de Google Search y Google Images
• datos de Yellow Pages, Booking, Yelp, Tripadvisor, Trustpilot e Indeed
• verificación de saldo de cuenta y gestión del ciclo de vida de solicitudes asíncronas

El servidor admite transportes stdio y HTTP, instalación basada en npm, autenticación alojada por encabezado o URL, y una forma de resultado normalizada structuredContent para clientes y agentes MCP.

Qué hace

Este servidor MCP expone fuentes de datos de Outscraper y flujos de trabajo de enriquecimiento a clientes compatibles con MCP.

Está diseñado para:

• descubrimiento de negocios y lugares
• recuperación de reseñas y fotos de Google Maps
• enriquecimiento de contactos y empresas
• extracción estructurada asistida por IA de una sola página con ai_scraper
• envío de solicitudes asíncronas y sondeo a través de requests_get

En la práctica, el servidor actúa como una capa MCP delgada sobre la API de Outscraper:

• los clientes MCP llaman a herramientas en este servidor
• el servidor se autentica con una clave de API de Outscraper
• las solicitudes se reenvían a los endpoints de Outscraper
• los resultados se devuelven en un envoltorio de herramienta MCP normalizado

Inicio rápido

set OUTSCRAPER_API_KEY=YOUR_API_KEY
npx -y outscraper-mcp

Para clientes MCP, configura:

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

Para flujos de trabajo orientados a tareas, ejemplos de copiar y pegar y habilidades de agente de ejemplo, consulta la carpeta examples.

Herramientas actuales

• 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 heredado para trustpilot_data)
• trustpilot_data
• tp_reviews (alias heredado 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

Estas herramientas están alineadas con las formas actuales documentadas de la API de Outscraper, incluyendo:

• 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
• enriquecimiento documentado de ai_chain_info mediante google-maps-search
• GET /profile/balance
• GET /requests/{requestId}
• DELETE /requests/{requestId}
• GET /requests

Forma unificada de resultado de herramienta

Cada herramienta ahora devuelve el mismo envoltorio estructurado:

{
  "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 cuando la respuesta es un envío asíncrono o expone metadatos de solicitud asíncrona.

Modo de ejecución

Las herramientas capaces de asíncrono ahora aceptan:

{
  "execution_mode": "auto"
}

Valores disponibles:

• auto: deja que el servidor MCP elija síncrono o asíncrono
• sync: fuerza el modo de respuesta directa
• async: fuerza el modo de envío asíncrono

El booleano antiguo async todavía se acepta por compatibilidad, pero execution_mode ahora tiene prioridad.

Instalación

La forma recomendada de usar este servidor MCP es desde npm.

Ejecutar desde npm

npx -y outscraper-mcp

Proporciona OUTSCRAPER_API_KEY a través de la configuración de tu cliente MCP o del entorno de shell.

El servidor carga automáticamente .env al inicio mediante dotenv.

En Windows, si un cliente no puede encontrar npx, usa la ruta completa de Node.js en su lugar, por ejemplo:

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

Seguridad

Los problemas sensibles a la seguridad deben informarse según SECURITY.md.

Modos de conexión

El servidor actualmente admite estos patrones de conexión:

1. MCP stdio local

Ideal para:

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

Fuente de autenticación:

• variable de entorno OUTSCRAPER_API_KEY

Transporte:

• proceso local sobre stdio

2. HTTP Streamable sin estado remoto

Ideal para:

• endpoints MCP alojados
• n8n
• proxy inverso o implementación basada en dominio
• uso remoto contenerizado

Fuente de autenticación cuando CLOUD_SERVICE=true:

• X-OUTSCRAPER-API-KEY
• X-API-KEY
• Authorization: Bearer <api-key>
• autenticación por ruta /v1/mcp/<api-key>

Transporte:

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

3. HTTP/SSE con estado remoto

Ideal para:

• uso de MCP basado en sesiones
• clientes que dependen de la semántica de transporte HTTP con estado

Fuente de autenticación cuando CLOUD_SERVICE=true:

• las mismas opciones de autenticación por encabezado o URL que HTTP sin estado

Transporte:

• POST /mcp
• GET /mcp
• DELETE /mcp
• y el mismo patrón de ruta /v1/mcp/<api-key>

Nota:

• el modo con estado almacena sesiones en la memoria del proceso, por lo que es más adecuado para una instancia única o implementación con sesiones fijas que para escalado horizontal

Conector ChatGPT

Si quieres conectar este servidor a ChatGPT como conector MCP remoto, la forma alojada más simple es:

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

Configuración recomendada:

1. Implementa el servidor sobre HTTPS detrás de un dominio real o proxy inverso.
2. Habilita el modo alojado con CLOUD_SERVICE=true.
3. Usa la ruta de autenticación por URL si el conector no puede adjuntar encabezados de autenticación personalizados.
4. Prefiere autenticación por encabezado para clientes servidor a servidor cuando haya encabezados personalizados disponibles.

Valores típicos del conector:

• Nombre: Outscraper MCP
• Descripción: Business discovery, Google Maps data, enrichment, search, and AI scraping
• URL del servidor MCP: https://your-domain.example/v1/mcp/YOUR_API_KEY
• Autenticación: None

Notas:

• La autenticación por URL es la opción más conveniente para configuraciones tipo conector, pero es menos privada que la autenticación por encabezado porque las URLs tienen más probabilidad de aparecer en registros.
• Evita túneles temporales que inyecten páginas de advertencia del navegador a menos que tu conector pueda omitirlas limpiamente.

Modo de autenticación por encabezado alojado

Si quieres comportamiento alojado, habilita:

set CLOUD_SERVICE=true

Entonces el llamador HTTP puede enviar la clave de API de Outscraper en uno de estos encabezados:

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

En el modo HTTP CLOUD_SERVICE=true, los encabezados de solicitud se usan como fuente de la clave de API. En el modo stdio local, OUTSCRAPER_API_KEY sigue siendo necesario.

Las solicitudes HTTP sin una de estas formas de autenticación se rechazan antes de que comience el procesamiento MCP.

Modo de autenticación por URL alojado

Para conectores estilo ChatGPT u otras configuraciones alojadas que no pueden enviar encabezados personalizados, también puedes pasar la clave de API en la ruta:

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

Esta ruta admite el mismo comportamiento MCP que /mcp, pero autentica desde la ruta de URL cuando CLOUD_SERVICE=true.

Para integraciones servidor a servidor, la autenticación por encabezado sigue siendo preferida porque las claves de API basadas en URL tienen más probabilidad de aparecer en registros.

Ejecutar con 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 autenticación por URL alojado:

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

Endpoint de salud:

http://localhost:3000/health

Ejecutar con Docker Compose

Este repositorio también incluye un docker-compose.yml para implementaciones alojadas/contenerizadas:

docker compose up --build -d

Comportamiento predeterminado del contenedor:

• vincula 3000:3000
• habilita CLOUD_SERVICE=true
• habilita HTTP Streamable sin estado
• escucha en 0.0.0.0
• usa https://api.outscraper.com como URL base de la API ascendente

Endpoints:

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

Notas importantes para el uso de Docker:

• este archivo compose está destinado al acceso remoto alojado, no a clientes stdio locales
• por defecto espera que los llamadores se autentiquen por solicitud, no a través de una única clave de API para todo el servidor
• si pones el servicio detrás de un dominio o proxy inverso, prefiere autenticación por encabezado para uso servidor a servidor
• la autenticación por URL está disponible principalmente para flujos de conector que no pueden adjuntar encabezados personalizados

Ejecutar con modo HTTP/SSE con estado

Este modo usa gestión de sesiones local:

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

También puedes habilitar el mismo modo con:

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

En este modo el servidor acepta:

• POST /mcp para inicializar y solicitudes posteriores
• GET /mcp para el flujo de sesión
• DELETE /mcp para la terminación de sesión

La sesión se rastrea a través del encabezado mcp-session-id.

La autenticación por URL alojada también funciona en modo con estado a través de:

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

Configuración del 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

Ejemplos de herramientas

Buscar negocios con filtros estructurados

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

El soporte de query en lenguaje natural en /businesses actualmente depende del comportamiento del analizador de Outscraper. En pruebas en vivo, los filters estructurados fueron confiables mientras que los valores de query de forma libre a menudo devolvían Could not parse query into a valid request format.

Extraer datos estructurados con 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"
}

Usa execution_mode: "async" si quieres un id de solicitud y planeas hacer sondeo más tarde con requests_get.

Obtener un negocio

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

Buscar en Google Maps

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

Obtener reseñas de Google Maps

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

Obtener información de empresas

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

Encontrar correos electrónicos y contactos

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

Validar direcciones de correo electrónico

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

Obtener fotos de Google Maps

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

Obtener información de cadenas

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

Obtener datos de negocios de Trustpilot

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

Buscar en Google

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

Buscar en Google Images

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

Buscar en Indeed

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

Verificar saldo de cuenta

{}

Eliminar solicitud asíncrona

{
  "request_id": "YOUR_REQUEST_ID"
}

Limitaciones conocidas

• businesses_search funciona de manera confiable con filters estructurados, pero los valores de query de formato libre en /businesses pueden fallar con Could not parse query into a valid request format.. Este comportamiento se reprodujo contra la API en vivo, no solo dentro de la capa MCP.
• ai_scraper funciona mejor a través de POST con un cuerpo JSON. En la validación en vivo, POST aceptó prompt y schema de manera confiable, mientras que las variantes de GET alrededor de schema y query_schema no coincidieron con el mismo comportamiento de manera consistente.
• Cuando los ejemplos de OpenAPI de Outscraper y el comportamiento de la API en vivo difieren, el comportamiento del endpoint en vivo debe tratarse como la fuente de verdad.
• businesses_search se expone intencionalmente aquí como una herramienta MCP síncrona porque la forma actual de OpenAPI de /businesses se basa en el cuerpo de la solicitud y no demostró ser un flujo de trabajo asíncrono estable durante la validación en vivo.
• execution_mode="auto" está impulsado por heurísticas. Está diseñado para elegir un valor predeterminado práctico, pero los llamadores que necesitan un comportamiento determinista deben usar explícitamente sync o async.
• El modo alojado HTTP requiere encabezados de autenticación correctos cuando CLOUD_SERVICE=true; el modo stdio aún espera OUTSCRAPER_API_KEY en el entorno del proceso.
• chain_info se implementa a partir del enriquecimiento documentado de ai_chain_info en google-maps-search, porque Outscraper actualmente no describe un endpoint independiente de chain info.
• builtwith no se expone actualmente como una herramienta porque Outscraper actualmente no documenta un endpoint dedicado de BuiltWith.

Notas de Selección de Herramientas

• Use businesses_search para el descubrimiento estructurado de negocios con filtros y paginación por cursor.
• Use businesses_get una vez que ya tenga un ID de negocio concreto.
• Use google_maps_search para el descubrimiento de lugares estilo Google Maps a partir de consultas de búsqueda humanas.
• Use google_maps_reviews cuando el usuario necesite específicamente datos de reseñas en lugar de descubrimiento de lugares.
• Use company_insights para firmografía y enriquecimiento de perfiles de empresas.
• Use emails_and_contacts para el descubrimiento de contactos a partir de dominios conocidos.
• Use requests_get, requests_list y requests_delete solo para la gestión del ciclo de vida asíncrono.
• Use balance_get para verificaciones de cuenta y facturación, no para la recuperación de datos de negocios.

Notas

• El servidor admite stdio, HTTP Streamable sin estado y modo HTTP/SSE local con estado.
• CLOUD_SERVICE=true permite la resolución de claves de API basada en encabezados para solicitudes HTTP.
• Para la publicación en npm, el contenido del paquete se limita intencionalmente a artefactos de ejecución y documentación.
• Los fragmentos de configuración específicos del cliente en este README están pensados como plantillas prácticas; la interfaz de configuración exacta y los nombres de las claves de configuración pueden variar ligeramente entre clientes y versiones de MCP.