Outscraper MCP

Official MCP server for Outscraper.

Connect AI agents to Outscraper for business discovery, Google Maps intelligence, company and contact enrichment, review analysis, search, and structured web extraction.

Best For

• local business prospecting and lead generation
• Google Maps place, photo, and review intelligence
• company and contact enrichment from known domains
• async data collection workflows with polling
• extracting structured information from a single page

Not Ideal For

• browser automation or multi-step UI interaction
• generic OAuth-based SaaS integrations
• arbitrary document search outside the Outscraper data surface
• website crawling sessions that require a persistent browser

Common Workflows

• find businesses with businesses_search, then enrich a chosen record with businesses_get
• search Google Maps places, then fetch reviews or photos for reputation analysis
• enrich a company domain, validate emails, and check contact coverage
• submit async jobs, then poll them with requests_get
• extract structured data from a page with ai_scraper

It exposes production-ready MCP tools for:

• business discovery and enrichment
• Google Maps places, reviews, photos, and chain detection
• company insights, emails, email validation, and phone enrichment
• Google Search and Google Images search
• Yellow Pages, Booking, Yelp, Tripadvisor, Trustpilot, and Indeed data
• account balance checks and async request lifecycle management

The server supports stdio and HTTP transports, npm-based installation, hosted header or URL auth, and a normalized structuredContent result shape for MCP clients and agents.

What It Does

This MCP server exposes Outscraper data sources and enrichment workflows to MCP-compatible clients.

It is designed for:

• business and place discovery
• Google Maps review and photo retrieval
• contact and company enrichment
• AI-assisted structured extraction from a single page with ai_scraper
• async request submission and polling through requests_get

In practice, the server acts as a thin MCP layer over the Outscraper API:

• MCP clients call tools on this server
• the server authenticates with an Outscraper API key
• requests are forwarded to Outscraper endpoints
• results are returned in a normalized MCP tool envelope

Quick Start

set OUTSCRAPER_API_KEY=YOUR_API_KEY
npx -y outscraper-mcp

For MCP clients, configure:

• command: npx
• args: ["-y", "outscraper-mcp"]
• env: OUTSCRAPER_API_KEY=YOUR_API_KEY

For task-oriented workflows, copy-paste examples, and example agent skills, see the examples folder.

Current Tools

• 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 (legacy alias for trustpilot_data)
• trustpilot_data
• tp_reviews (legacy alias for 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

These tools are aligned to the current documented Outscraper API shapes, including:

• 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
• documented ai_chain_info enrichment via google-maps-search
• GET /profile/balance
• GET /requests/{requestId}
• DELETE /requests/{requestId}
• GET /requests

Unified Tool Result Shape

Every tool now returns the same structured envelope:

{
  "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 is present when the response is an async submission or exposes async request metadata.

Execution Mode

Async-capable tools now accept:

{
  "execution_mode": "auto"
}

Available values:

• auto: let the MCP server choose sync or async
• sync: force direct response mode
• async: force async submission mode

The old boolean async is still accepted for compatibility, but execution_mode now has priority.

Install

The recommended way to use this MCP server is from npm.

Run from npm

npx -y outscraper-mcp

Provide OUTSCRAPER_API_KEY through your MCP client config or shell environment.

The server auto-loads .env on startup via dotenv.

On Windows, if a client cannot find npx, use the full Node.js path instead, for example:

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

Security

Security-sensitive issues should be reported according to SECURITY.md.

Connection Modes

The server currently supports these connection patterns:

1. Local stdio MCP

Best for:

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

Auth source:

• OUTSCRAPER_API_KEY environment variable

Transport:

• local process over stdio

2. Remote stateless Streamable HTTP

Best for:

• hosted MCP endpoints
• n8n
• reverse proxy or domain-based deployment
• containerized remote usage

Auth source when CLOUD_SERVICE=true:

• X-OUTSCRAPER-API-KEY
• X-API-KEY
• Authorization: Bearer <api-key>
• /v1/mcp/<api-key> path auth

Transport:

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

3. Remote stateful HTTP/SSE

Best for:

• session-based MCP usage
• clients that rely on stateful HTTP transport semantics

Auth source when CLOUD_SERVICE=true:

• the same header or URL-based auth options as stateless HTTP

Transport:

• POST /mcp
• GET /mcp
• DELETE /mcp
• and the same /v1/mcp/<api-key> route pattern

Note:

• stateful mode stores sessions in process memory, so it is better suited to a single instance or sticky-session deployment than horizontal scaling

ChatGPT Connector

If you want to connect this server to ChatGPT as a remote MCP connector, the simplest hosted form is:

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

Recommended setup:

1. Deploy the server over HTTPS behind a real domain or reverse proxy.
2. Enable hosted mode with CLOUD_SERVICE=true.
3. Use the URL-auth route if the connector cannot attach custom auth headers.
4. Prefer header auth for server-to-server clients when custom headers are available.

Typical connector values:

• Name: Outscraper MCP
• Description: Business discovery, Google Maps data, enrichment, search, and AI scraping
• MCP Server URL: https://your-domain.example/v1/mcp/YOUR_API_KEY
• Authentication: None

Notes:

• URL-auth is the most convenient option for connector-style setup, but it is less private than header auth because URLs are more likely to appear in logs.
• Avoid temporary tunnels that inject browser warning pages unless your connector can bypass them cleanly.

Hosted Header Auth Mode

If you want hosted behavior, enable:

set CLOUD_SERVICE=true

Then the HTTP caller can send the Outscraper API key in one of these headers:

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

In CLOUD_SERVICE=true HTTP mode, request headers are used as the API key source. In local stdio mode, OUTSCRAPER_API_KEY is still required. HTTP requests without one of these auth forms are rejected before MCP processing begins.

Hosted URL Auth Mode

For ChatGPT-style connectors or other hosted setups that cannot send custom headers, you can also pass the API key in the path:

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

This route supports the same MCP behavior as /mcp, but authenticates from the URL path when CLOUD_SERVICE=true. For server-to-server integrations, header auth is still preferred because URL-based API keys are more likely to appear in logs.

Run with Streamable HTTP

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

MCP endpoint:

http://localhost:3000/mcp

Hosted URL auth endpoint:

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

Health endpoint:

http://localhost:3000/health

Run with Docker Compose

This repository also includes a docker-compose.yml for hosted/container deployments:

docker compose up --build -d

Default container behavior:

• binds 3000:3000
• enables CLOUD_SERVICE=true
• enables stateless Streamable HTTP
• listens on 0.0.0.0
• uses https://api.outscraper.com as the upstream API base URL

Endpoints:

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

Important notes for Docker usage:

• this compose file is intended for hosted remote access, not local stdio clients
• by default it expects callers to authenticate per request, not through a single server-wide API key
• if you put the service behind a domain or reverse proxy, prefer header auth for server-to-server usage
• URL auth is available mainly for connector flows that cannot attach custom headers

Run with Stateful HTTP/SSE Mode

This mode uses local session management: