{
  "markdown": "# Outscraper MCP\n\nOfficial MCP server for [Outscraper](https://outscraper.com/).\n\nConnect AI agents to Outscraper for business discovery, Google Maps intelligence, company and contact enrichment, review analysis, search, and structured web extraction.\n\n## Best For\n\n- local business prospecting and lead generation\n- Google Maps place, photo, and review intelligence\n- company and contact enrichment from known domains\n- async data collection workflows with polling\n- extracting structured information from a single page\n\n## Not Ideal For\n\n- browser automation or multi-step UI interaction\n- generic OAuth-based SaaS integrations\n- arbitrary document search outside the Outscraper data surface\n- website crawling sessions that require a persistent browser\n\n## Common Workflows\n\n- find businesses with `businesses_search`, then enrich a chosen record with `businesses_get`\n- search Google Maps places, then fetch reviews or photos for reputation analysis\n- enrich a company domain, validate emails, and check contact coverage\n- submit async jobs, then poll them with `requests_get`\n- extract structured data from a page with `ai_scraper`\n\nIt exposes production-ready MCP tools for:\n\n- business discovery and enrichment\n- Google Maps places, reviews, photos, and chain detection\n- company insights, emails, email validation, and phone enrichment\n- Google Search and Google Images search\n- Yellow Pages, Booking, Yelp, Tripadvisor, Trustpilot, and Indeed data\n- account balance checks and async request lifecycle management\n\nThe 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.\n\n## What It Does\n\nThis MCP server exposes Outscraper data sources and enrichment workflows to MCP-compatible clients.\n\nIt is designed for:\n\n- business and place discovery\n- Google Maps review and photo retrieval\n- contact and company enrichment\n- AI-assisted structured extraction from a single page with `ai_scraper`\n- async request submission and polling through `requests_get`\n\nIn practice, the server acts as a thin MCP layer over the Outscraper API:\n\n- MCP clients call tools on this server\n- the server authenticates with an Outscraper API key\n- requests are forwarded to Outscraper endpoints\n- results are returned in a normalized MCP tool envelope\n\n## Quick Start\n\n```bash\nset OUTSCRAPER_API_KEY=YOUR_API_KEY\nnpx -y outscraper-mcp\n```\n\nFor MCP clients, configure:\n\n- command: `npx`\n- args: `[\"-y\", \"outscraper-mcp\"]`\n- env: `OUTSCRAPER_API_KEY=YOUR_API_KEY`\n\nFor task-oriented workflows, copy-paste examples, and example agent skills, see the [examples](./examples/README.md) folder.\n\n## Current Tools\n\n- `ping`\n- `businesses_search`\n- `businesses_get`\n- `ai_scraper`\n- `google_maps_search`\n- `google_maps_reviews`\n- `company_insights`\n- `emails_and_contacts`\n- `emails_validator`\n- `google_maps_photos`\n- `chain_info`\n- `yellowpages_search`\n- `booking_reviews`\n- `phones_enricher`\n- `tp_data` (legacy alias for `trustpilot_data`)\n- `trustpilot_data`\n- `tp_reviews` (legacy alias for `trustpilot_reviews`)\n- `trustpilot_reviews`\n- `yelp_reviews`\n- `tripadvisor_search`\n- `tripadvisor_reviews`\n- `google_search`\n- `google_search_images`\n- `indeed_search`\n- `balance_get`\n- `requests_get`\n- `requests_list`\n- `requests_delete`\n\nThese tools are aligned to the current documented Outscraper API shapes, including:\n\n- `POST /businesses`\n- `POST /ai-scraper`\n- `GET /businesses/{business_id}`\n- `GET /google-maps-search`\n- `GET /google-maps-photos`\n- `GET /google-search`\n- `GET /google-search-images`\n- `GET /yellowpages-search`\n- `GET /booking-reviews`\n- `GET /phones-enricher`\n- `GET /trustpilot`\n- `GET /trustpilot-reviews`\n- `GET /yelp-reviews`\n- `GET /tripadvisor-search`\n- `GET /tripadvisor-reviews`\n- `GET /indeed-search`\n- `GET /google-maps-reviews`\n- `GET /company-insights`\n- `GET /emails-and-contacts`\n- `GET /email-validator`\n- documented `ai_chain_info` enrichment via `google-maps-search`\n- `GET /profile/balance`\n- `GET /requests/{requestId}`\n- `DELETE /requests/{requestId}`\n- `GET /requests`\n\n### Unified Tool Result Shape\n\nEvery tool now returns the same structured envelope:\n\n```json\n{\n  \"data\": {},\n  \"meta\": {\n    \"service\": \"company_insights\",\n    \"operation\": \"get\"\n  },\n  \"async\": {\n    \"id\": \"request-id\",\n    \"status\": \"Pending\",\n    \"results_location\": \"https://api.outscraper.com/requests/request-id\",\n    \"is_async_submission\": true,\n    \"next_step\": \"Call requests_get with request_id=\\\"request-id\\\" to check progress.\"\n  }\n}\n```\n\n`async` is present when the response is an async submission or exposes async request metadata.\n\n### Execution Mode\n\nAsync-capable tools now accept:\n\n```json\n{\n  \"execution_mode\": \"auto\"\n}\n```\n\nAvailable values:\n\n- `auto`: let the MCP server choose sync or async\n- `sync`: force direct response mode\n- `async`: force async submission mode\n\nThe old boolean `async` is still accepted for compatibility, but `execution_mode` now has priority.\n\n## Install\n\nThe recommended way to use this MCP server is from npm.\n\n### Run from npm\n\n```bash\nnpx -y outscraper-mcp\n```\n\nProvide `OUTSCRAPER_API_KEY` through your MCP client config or shell environment.\n\nThe server auto-loads `.env` on startup via `dotenv`.\n\nOn Windows, if a client cannot find `npx`, use the full Node.js path instead, for example:\n\n```json\n{\n  \"command\": \"C:\\\\Program Files\\\\nodejs\\\\npx.cmd\",\n  \"args\": [\"-y\", \"outscraper-mcp\"]\n}\n```\n\n## Security\n\nSecurity-sensitive issues should be reported according to [SECURITY.md](./SECURITY.md).\n\n## Connection Modes\n\nThe server currently supports these connection patterns:\n\n### 1. Local stdio MCP\n\nBest for:\n\n- Claude Desktop\n- Claude Code\n- Cursor\n- VS Code\n- Windsurf\n- local MCP development\n\nAuth source:\n\n- `OUTSCRAPER_API_KEY` environment variable\n\nTransport:\n\n- local process over stdio\n\n### 2. Remote stateless Streamable HTTP\n\nBest for:\n\n- hosted MCP endpoints\n- n8n\n- reverse proxy or domain-based deployment\n- containerized remote usage\n\nAuth source when `CLOUD_SERVICE=true`:\n\n- `X-OUTSCRAPER-API-KEY`\n- `X-API-KEY`\n- `Authorization: Bearer <api-key>`\n- `/v1/mcp/<api-key>` path auth\n\nTransport:\n\n- HTTP `POST /mcp`\n- HTTP `POST /v1/mcp/<api-key>`\n\n### 3. Remote stateful HTTP/SSE\n\nBest for:\n\n- session-based MCP usage\n- clients that rely on stateful HTTP transport semantics\n\nAuth source when `CLOUD_SERVICE=true`:\n\n- the same header or URL-based auth options as stateless HTTP\n\nTransport:\n\n- `POST /mcp`\n- `GET /mcp`\n- `DELETE /mcp`\n- and the same `/v1/mcp/<api-key>` route pattern\n\nNote:\n\n- stateful mode stores sessions in process memory, so it is better suited to a single instance or sticky-session deployment than horizontal scaling\n\n## ChatGPT Connector\n\nIf you want to connect this server to ChatGPT as a remote MCP connector, the simplest hosted form is:\n\n```text\nhttps://your-domain.example/v1/mcp/YOUR_API_KEY\n```\n\nRecommended setup:\n\n1. Deploy the server over HTTPS behind a real domain or reverse proxy.\n2. Enable hosted mode with `CLOUD_SERVICE=true`.\n3. Use the URL-auth route if the connector cannot attach custom auth headers.\n4. Prefer header auth for server-to-server clients when custom headers are available.\n\nTypical connector values:\n\n- Name: `Outscraper MCP`\n- Description: `Business discovery, Google Maps data, enrichment, search, and AI scraping`\n- MCP Server URL: `https://your-domain.example/v1/mcp/YOUR_API_KEY`\n- Authentication: `None`\n\nNotes:\n\n- 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.\n- Avoid temporary tunnels that inject browser warning pages unless your connector can bypass them cleanly.\n\n### Hosted Header Auth Mode\n\nIf you want hosted behavior, enable:\n\n```bash\nset CLOUD_SERVICE=true\n```\n\nThen the HTTP caller can send the Outscraper API key in one of these headers:\n\n- `Authorization: Bearer <api-key>`\n- `X-API-KEY: <api-key>`\n- `X-OUTSCRAPER-API-KEY: <api-key>`\n\nIn `CLOUD_SERVICE=true` HTTP mode, request headers are used as the API key source. In local stdio mode, `OUTSCRAPER_API_KEY` is still required.\nHTTP requests without one of these auth forms are rejected before MCP processing begins.\n\n### Hosted URL Auth Mode\n\nFor ChatGPT-style connectors or other hosted setups that cannot send custom headers, you can also pass the API key in the path:\n\n```text\nhttp://localhost:3000/v1/mcp/YOUR_API_KEY\n```\n\nThis route supports the same MCP behavior as `/mcp`, but authenticates from the URL path when `CLOUD_SERVICE=true`.\nFor server-to-server integrations, header auth is still preferred because URL-based API keys are more likely to appear in logs.\n\n### Run with Streamable HTTP\n\n```bash\nset HTTP_STREAMABLE_SERVER=true\nset HOST=localhost\nset PORT=3000\nnpx -y outscraper-mcp\n```\n\nMCP endpoint:\n\n```text\nhttp://localhost:3000/mcp\n```\n\nHosted URL auth endpoint:\n\n```text\nhttp://localhost:3000/v1/mcp/YOUR_API_KEY\n```\n\nHealth endpoint:\n\n```text\nhttp://localhost:3000/health\n```\n\n### Run with Docker Compose\n\nThis repository also includes a `docker-compose.yml` for hosted/container deployments:\n\n```bash\ndocker compose up --build -d\n```\n\nDefault container behavior:\n\n- binds `3000:3000`\n- enables `CLOUD_SERVICE=true`\n- enables stateless Streamable HTTP\n- listens on `0.0.0.0`\n- uses `https://api.outscraper.com` as the upstream API base URL\n\nEndpoints:\n\n```text\nhttp://localhost:3000/mcp\nhttp://localhost:3000/v1/mcp/YOUR_API_KEY\nhttp://localhost:3000/health\n```\n\nImportant notes for Docker usage:\n\n- this compose file is intended for hosted remote access, not local stdio clients\n- by default it expects callers to authenticate per request, not through a single server-wide API key\n- if you put the service behind a domain or reverse proxy, prefer header auth for server-to-server usage\n- URL auth is available mainly for connector flows that cannot attach custom headers\n\n### Run with Stateful HTTP/SSE Mode\n\nThis mode uses local session management:\n\n```bash\nset SSE_LOCAL=true\nset HOST=localhost\nset PORT=3000\nnpx -y outscraper-mcp\n```\n\nYou can also enable the same mode with:\n\n```bash\nset HTTP_STATEFUL_SERVER=true\nset HOST=localhost\nset PORT=3000\nnpx -y outscraper-mcp\n```\n\nIn this mode the server accepts:\n\n- `POST /mcp` for initialize and subsequent requests\n- `GET /mcp` for the session stream\n- `DELETE /mcp` for session termination\n\nThe session is tracked through the `mcp-session-id` header.\n\nHosted URL auth also works in stateful mode through:\n\n```text\nhttp://localhost:3000/v1/mcp/YOUR_API_KEY\n```\n\n## Client Setup\n\n<details>\n<summary>Claude Desktop</summary>\n\nAdd this to your Claude Desktop MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"outscraper\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"outscraper-mcp\"],\n      \"env\": {\n        \"OUTSCRAPER_API_KEY\": \"YOUR_API_KEY\"\n      }\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary>Claude Code</summary>\n\nAdd the server with the Claude Code CLI:\n\n```bash\nclaude mcp add outscraper -e OUTSCRAPER_API_KEY=YOUR_API_KEY -- npx -y outscraper-mcp\n```\n\n</details>\n\n<details>\n<summary>Cursor</summary>\n\nAdd this to your global MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"outscraper\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"outscraper-mcp\"],\n      \"env\": {\n        \"OUTSCRAPER_API_KEY\": \"YOUR_API_KEY\"\n      }\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary>Windsurf</summary>\n\nAdd this to your MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"outscraper\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"outscraper-mcp\"],\n      \"env\": {\n        \"OUTSCRAPER_API_KEY\": \"YOUR_API_KEY\"\n      }\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary>VS Code</summary>\n\nFor `settings.json`:\n\n```json\n{\n  \"mcp\": {\n    \"inputs\": [\n      {\n        \"type\": \"promptString\",\n        \"id\": \"outscraperApiKey\",\n        \"description\": \"Outscraper API Key\",\n        \"password\": true\n      }\n    ],\n    \"servers\": {\n      \"outscraper\": {\n        \"command\": \"npx\",\n        \"args\": [\"-y\", \"outscraper-mcp\"],\n        \"env\": {\n          \"OUTSCRAPER_API_KEY\": \"${input:outscraperApiKey}\"\n        }\n      }\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary>Cline / Roo Code / other command-based MCP clients</summary>\n\nUse the standard stdio command form:\n\n```json\n{\n  \"mcpServers\": {\n    \"outscraper\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"outscraper-mcp\"],\n      \"env\": {\n        \"OUTSCRAPER_API_KEY\": \"YOUR_API_KEY\"\n      }\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary>n8n</summary>\n\nFor n8n or other HTTP MCP clients, run the server in Streamable HTTP mode:\n\n```bash\nset HTTP_STREAMABLE_SERVER=true\nset HOST=localhost\nset PORT=3000\nset OUTSCRAPER_API_KEY=YOUR_API_KEY\nnpx -y outscraper-mcp\n```\n\nThen use:\n\n```text\nhttp://localhost:3000/mcp\n```\n\n</details>\n\n## Tool Examples\n\n### Search businesses with structured filters\n\n```json\n{\n  \"filters\": {\n    \"country_code\": \"US\",\n    \"states\": [\"NY\"],\n    \"cities\": [\"New York\"],\n    \"types\": [\"restaurant\", \"cafe\"]\n  },\n  \"fields\": [\"name\", \"phone\", \"website\", \"address\", \"rating\", \"reviews\"],\n  \"limit\": 25\n}\n```\n\nNatural-language `query` support on `/businesses` currently depends on Outscraper's own parser behavior. In live testing, structured `filters` were reliable while free-form `query` values often returned `Could not parse query into a valid request format.`\n\n### Extract structured data with AI Scraper\n\n```json\n{\n  \"query\": \"https://outscraper.com\",\n  \"prompt\": \"Extract company name, company description, and people mentioned on the page.\",\n  \"schema\": {\n    \"type\": \"object\",\n    \"required\": [],\n    \"properties\": {\n      \"company_name\": { \"type\": \"string\" },\n      \"company_description\": { \"type\": \"string\" },\n      \"people\": {\n        \"type\": \"array\",\n        \"items\": { \"type\": \"string\" }\n      }\n    }\n  },\n  \"execution_mode\": \"sync\"\n}\n```\n\nUse `execution_mode: \"async\"` if you want a request id and plan to poll later with `requests_get`.\n\n### Get one business\n\n```json\n{\n  \"business_id\": \"YOUR_BUSINESS_ID\",\n  \"fields\": [\"name\", \"phone\", \"website\", \"address\", \"rating\", \"reviews\"]\n}\n```\n\n### Search Google Maps\n\n```json\n{\n  \"query\": [\"restaurants brooklyn usa\"],\n  \"limit\": 20,\n  \"language\": \"en\",\n  \"region\": \"us\"\n}\n```\n\n### Fetch Google Maps reviews\n\n```json\n{\n  \"query\": [\"ChIJrc9T9fpYwokRdvjYRHT8nI4\"],\n  \"reviews_limit\": 20,\n  \"sort\": \"newest\",\n  \"language\": \"en\"\n}\n```\n\n### Get company insights\n\n```json\n{\n  \"query\": [\"outscraper.com\"],\n  \"fields\": [\"name\", \"description\", \"industry\"],\n  \"execution_mode\": \"async\"\n}\n```\n\n### Find emails and contacts\n\n```json\n{\n  \"query\": [\"outscraper.com\"],\n  \"preferred_contacts\": [\"technical\", \"decision makers\"],\n  \"execution_mode\": \"sync\"\n}\n```\n\n### Validate email addresses\n\n```json\n{\n  \"query\": [\"support@outscraper.com\"],\n  \"execution_mode\": \"sync\"\n}\n```\n\n### Fetch Google Maps photos\n\n```json\n{\n  \"query\": [\"NoMad Restaurant, NY, USA\"],\n  \"photos_limit\": 5,\n  \"limit\": 1,\n  \"execution_mode\": \"sync\"\n}\n```\n\n### Get chain info\n\n```json\n{\n  \"query\": [\"Starbucks, New York, NY, USA\"],\n  \"limit\": 1,\n  \"execution_mode\": \"sync\"\n}\n```\n\n### Get Trustpilot business data\n\n```json\n{\n  \"query\": [\"outscraper.com\"],\n  \"execution_mode\": \"sync\"\n}\n```\n\n### Search Google\n\n```json\n{\n  \"query\": [\"outscraper\"],\n  \"pages_per_query\": 1,\n  \"execution_mode\": \"sync\"\n}\n```\n\n### Search Google Images\n\n```json\n{\n  \"query\": [\"outscraper\"],\n  \"limit\": 5,\n  \"execution_mode\": \"sync\"\n}\n```\n\n### Search Indeed\n\n```json\n{\n  \"query\": [\"https://www.indeed.com/jobs?q=software+engineer&l=New+York%2C+NY\"],\n  \"limit\": 10,\n  \"execution_mode\": \"sync\"\n}\n```\n\n### Check account balance\n\n```json\n{}\n```\n\n### Delete async request\n\n```json\n{\n  \"request_id\": \"YOUR_REQUEST_ID\"\n}\n```\n\n## Known Limitations\n\n- `businesses_search` works reliably with structured `filters`, but free-form `query` values on `/businesses` may fail with `Could not parse query into a valid request format.` This behavior was reproduced against the live API, not only inside the MCP layer.\n- `ai_scraper` works best through `POST` with a JSON body. In live validation, `POST` accepted `prompt` and `schema` reliably, while `GET` variants around `schema` and `query_schema` did not match the same behavior consistently.\n- When Outscraper OpenAPI examples and live API behavior differ, live endpoint behavior should be treated as the source of truth.\n- `businesses_search` is intentionally exposed here as a synchronous MCP tool because the current `/businesses` OpenAPI shape is request-body-based and did not prove to be a stable async-style workflow during live validation.\n- `execution_mode=\"auto\"` is heuristic-driven. It is designed to choose a practical default, but callers that need deterministic behavior should explicitly use `sync` or `async`.\n- HTTP hosted mode requires correct auth headers when `CLOUD_SERVICE=true`; stdio mode still expects `OUTSCRAPER_API_KEY` in the process environment.\n- `chain_info` is implemented from the documented `ai_chain_info` enrichment on `google-maps-search`, because Outscraper currently does not describe a standalone `chain info` endpoint.\n- `builtwith` is not currently exposed as a tool because Outscraper currently does not document a dedicated BuiltWith endpoint.\n\n## Tool Selection Notes\n\n- Use `businesses_search` for structured business discovery with filters and cursor pagination.\n- Use `businesses_get` once you already have a concrete business id.\n- Use `google_maps_search` for Google Maps-style place discovery from human search queries.\n- Use `google_maps_reviews` when the user specifically needs review data rather than place discovery.\n- Use `company_insights` for firmographics and company profile enrichment.\n- Use `emails_and_contacts` for contact discovery from known domains.\n- Use `requests_get`, `requests_list`, and `requests_delete` only for async lifecycle management.\n- Use `balance_get` for account and billing checks, not business data retrieval.\n\n## Notes\n\n- The server supports stdio, stateless Streamable HTTP, and stateful local HTTP/SSE mode.\n- `CLOUD_SERVICE=true` enables header-based API key resolution for HTTP requests.\n- For npm publication, package contents are intentionally limited to runtime artifacts and docs.\n- Client-specific config snippets in this README are meant as practical templates; the exact settings UI and config key names may vary slightly between MCP clients and versions.\n",
  "bytes": 18322,
  "sha": "47066719561de20864857c67f8d8602c2fca2ff45bbe14d19318652a818cd5bf",
  "repo_slug": "outscraper/outscraper-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_outscraper_outscraper_mcp_serv_31ef3a12/readme"
}