Outscraper Mcp Server

Outscraper MCP

Outscraper 的官方 MCP 服务。

将 AI Agent 接入 Outscraper，开展商业信息发现、Google Maps 情报分析、公司和联系人信息补全、评论分析、搜索及结构化网页提取。

最适合用于

• 本地商家挖掘和潜在客户开发
• Google Maps 地点、照片和评论情报分析
• 根据已知域名补全公司和联系人信息
• 支持轮询的异步数据采集工作流
• 从单个页面提取结构化信息

不适合用于

• 浏览器自动化或多步骤 UI 交互
• 通用的 OAuth SaaS 集成
• 在 Outscraper 数据范围之外搜索任意文档
• 需要持久浏览器的网站爬取会话

常见工作流

• 使用 businesses_search 查找商家，再用 businesses_get 补全选定记录
• 搜索 Google Maps 地点，再获取评论或照片以分析口碑
• 补全公司域名信息、验证电子邮件，并检查联系人覆盖情况
• 提交异步任务，再使用 requests_get 轮询
• 使用 ai_scraper 从页面提取结构化数据

它提供可用于生产环境的 MCP 工具，涵盖：

• 商家发现和信息补全
• Google Maps 地点、评论、照片和连锁店检测
• 公司洞察、电子邮件、电子邮件验证和电话号码补全
• Google Search 和 Google Images 搜索
• Yellow Pages、Booking、Yelp、Tripadvisor、Trustpilot 和 Indeed 数据
• 账户余额查询和异步请求生命周期管理

该服务支持 stdio 和 HTTP 传输、基于 npm 的安装、托管式请求头或 URL 身份验证，以及供 MCP 客户端和 Agent 使用的标准化 structuredContent 结果格式。

功能说明

此 MCP 服务向兼容 MCP 的客户端开放 Outscraper 数据源和信息补全工作流。

它适用于：

• 商家和地点发现
• Google Maps 评论和照片获取
• 联系人和公司信息补全
• 使用 ai_scraper 从单个页面进行 AI 辅助结构化提取
• 通过 requests_get 提交和轮询异步请求

在实际使用中，该服务是 Outscraper API 之上的轻量 MCP 层：

• MCP 客户端调用此服务上的工具
• 服务使用 Outscraper API 密钥进行身份验证
• 请求会转发到 Outscraper 端点
• 结果会以标准化的 MCP 工具封装格式返回

快速开始

set OUTSCRAPER_API_KEY=YOUR_API_KEY
npx -y outscraper-mcp

对于 MCP 客户端，请配置：

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

有关面向任务的工作流、可直接复制粘贴的示例以及示例 Agent 技能，请参阅 examples 文件夹。

当前工具

• 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（trustpilot_data 的旧别名）
• trustpilot_data
• tp_reviews（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

这些工具与当前文档中描述的 Outscraper API 格式保持一致，包括：

• 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
• 通过 google-maps-search 实现文档中描述的 ai_chain_info 补充信息
• GET /profile/balance
• GET /requests/{requestId}
• DELETE /requests/{requestId}
• GET /requests

统一的工具结果格式

每个工具现在都会返回相同的结构化封装：

{
  "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。

执行模式

现在支持异步的工具接受：

{
  "execution_mode": "auto"
}

可用值：

• auto：由 MCP 服务选择同步或异步模式
• sync：强制使用直接响应模式
• async：强制使用异步提交模式

为兼容性，仍接受旧的布尔值 async，但现在 execution_mode 优先级更高。

安装

推荐通过 npm 使用此 MCP 服务。

通过 npm 运行

npx -y outscraper-mcp

通过 MCP 客户端配置或 Shell 环境提供 OUTSCRAPER_API_KEY。

服务启动时会通过 dotenv 自动加载 .env。

在 Windows 上，如果客户端找不到 npx，请改用完整的 Node.js 路径，例如：

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

安全

请按照 SECURITY.md 报告安全敏感问题。

连接模式

此服务目前支持以下连接模式：

1. 本地 stdio MCP

适用于：

• Claude Desktop
• Claude Code
• Cursor
• VS Code
• Windsurf
• 本地 MCP 开发

认证来源：

• OUTSCRAPER_API_KEY 环境变量

传输方式：

• 通过 stdio 运行的本地进程

2. 远程无状态 Streamable HTTP

适用于：

• 托管的 MCP 端点
• n8n
• 反向代理或基于域名的部署
• 容器化远程使用

当 CLOUD_SERVICE=true 时的认证来源：

• X-OUTSCRAPER-API-KEY
• X-API-KEY
• Authorization: Bearer <api-key>
• /v1/mcp/<api-key> 路径认证

传输方式：

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

3. 远程有状态 HTTP/SSE

适用于：

• 基于会话的 MCP 使用
• 依赖有状态 HTTP 传输语义的客户端

当 CLOUD_SERVICE=true 时的认证来源：

• 与无状态 HTTP 相同的请求头或基于 URL 的认证选项

传输方式：

• POST /mcp
• GET /mcp
• DELETE /mcp
• 以及相同的 /v1/mcp/<api-key> 路由模式

注意：

• 有状态模式会将会话存储在进程内存中，因此比起水平扩展，更适合单实例或粘性会话部署

ChatGPT 连接器

如果你想将此服务连接到 ChatGPT，作为远程 MCP 连接器，最简单的托管方式是：

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

推荐设置：

1. 将服务部署在 HTTPS 上，并置于真实域名或反向代理之后。
2. 启用托管模式：CLOUD_SERVICE=true。
3. 如果连接器无法附加自定义身份验证标头，请使用 URL 身份验证路由。
4. 如果可以使用自定义标头，服务器到服务器的客户端优先使用标头身份验证。

典型的连接器配置：

• 名称：Outscraper MCP
• 描述：Business discovery, Google Maps data, enrichment, search, and AI scraping
• MCP 服务 URL：https://your-domain.example/v1/mcp/YOUR_API_KEY
• 身份验证：None

注意：

• URL 身份验证是最方便的连接器设置方式，但不如标头身份验证私密，因为 URL 更容易出现在日志中。
• 除非连接器能妥善绕过浏览器警告页面，否则请避免使用会注入此类页面的临时隧道。

托管标头身份验证模式

如果要启用托管行为，请设置：

set CLOUD_SERVICE=true

然后，HTTP 调用方可以通过以下任一标头发送 Outscraper API 密钥：

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

在 CLOUD_SERVICE=true HTTP 模式下，请求标头用作 API 密钥来源。在本地 stdio 模式下，仍然需要 OUTSCRAPER_API_KEY。 不包含上述任一种身份验证形式的 HTTP 请求会在 MCP 处理开始前被拒绝。

托管 URL 身份验证模式

对于 ChatGPT 风格的连接器或其他无法发送自定义标头的托管设置，也可以在路径中传入 API 密钥：

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

此路由支持与 /mcp 相同的 MCP 行为，但在 CLOUD_SERVICE=true 时从 URL 路径进行身份验证。 对于服务器到服务器的集成，仍然优先使用标头身份验证，因为基于 URL 的 API 密钥更容易出现在日志中。

使用 Streamable HTTP 运行

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

MCP 端点：

http://localhost:3000/mcp

托管 URL 身份验证端点：

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

健康检查端点：

http://localhost:3000/health

使用 Docker Compose 运行

此代码库还包含一个用于托管／容器部署的 docker-compose.yml：

docker compose up --build -d

容器默认行为：

• 绑定 3000:3000
• 启用 CLOUD_SERVICE=true
• 启用无状态 Streamable HTTP
• 监听 0.0.0.0
• 使用 https://api.outscraper.com 作为上游 API 基础 URL

端点：

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

Docker 使用重要说明：

• 此 compose 文件用于托管远程访问，不适用于本地 stdio 客户端
• 默认情况下，它要求调用方在每个请求中进行身份验证，而不是使用单个服务级 API 密钥
• 如果将服务置于域名或反向代理之后，服务器到服务器的使用场景优先采用标头身份验证
• URL 身份验证主要适用于无法附加自定义标头的连接器工作流

使用有状态 HTTP/SSE 模式运行

此模式使用本地会话管理：

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

也可以通过以下方式启用相同模式：

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

在此模式下，服务接受：

• POST /mcp，用于初始化和后续请求
• GET /mcp，用于会话流
• DELETE /mcp，用于终止会话

会话通过 mcp-session-id 标头进行跟踪。

有状态模式也支持通过以下路由进行托管 URL 身份验证：

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

客户端设置

{
  "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

使用结构化筛选条件搜索企业

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

目前，/businesses 上对自然语言 query 的支持取决于 Outscraper 自身的解析器行为。在实时测试中，结构化 filters 表现可靠，而自由格式的 query 值经常返回 Could not parse query into a valid request format.

使用 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"
}

如果需要请求 ID 并计划稍后使用 requests_get 轮询，请使用 execution_mode: "async"。

获取单个企业

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

搜索 Google 地图

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

获取 Google 地图评论

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

获取企业洞察

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

查找电子邮件和联系人

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

验证电子邮件地址

{
  "query": ["[email protected]"],
  "execution_mode": "sync"
}

获取 Google 地图照片

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

获取连锁企业信息

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

获取 Trustpilot 企业数据

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

搜索 Google

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

搜索 Google 图片

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

搜索 Indeed

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

检查账户余额

{}

删除异步请求

{
  "request_id": "YOUR_REQUEST_ID"
}

已知限制

• businesses_search 使用结构化 filters 时运行可靠，但 /businesses 上的自由格式 query 值可能会因 Could not parse query into a valid request format. 而失败。此行为已在实时 API 上复现，并非仅发生在 MCP 层。
• ai_scraper 最适合通过带有 JSON 正文的 POST 调用。在实时验证中，POST 能可靠接受 prompt 和 schema，而围绕 schema 和 query_schema 的 GET 变体无法始终保持一致的行为。
• 当 Outscraper OpenAPI 示例与实时 API 行为不一致时，应以实时端点行为为准。
• 此处有意将 businesses_search 作为同步 MCP 工具提供，因为当前 /businesses 的 OpenAPI 形式基于请求正文，且在实时验证中未能证明其异步式工作流足够稳定。
• execution_mode="auto" 由启发式规则驱动，旨在选择实用的默认方式；需要确定性行为的调用方应明确使用 sync 或 async。
• 当 CLOUD_SERVICE=true 时，HTTP 托管模式需要正确的身份验证标头；stdio 模式仍要求在进程环境中设置 OUTSCRAPER_API_KEY。
• chain_info 根据 google-maps-search 上文档所述的 ai_chain_info 补充信息实现，因为 Outscraper 目前未说明存在独立的 chain info 端点。
• 目前未将 builtwith 作为工具提供，因为 Outscraper 目前未记录专用的 BuiltWith 端点。

工具选择说明

• 使用 businesses_search，通过筛选条件和游标分页进行结构化企业发现。
• 已有具体企业 ID 时，使用 businesses_get。
• 使用 google_maps_search，根据用户的搜索查询发现 Google 地图风格的地点。
• 用户明确需要评论数据而非地点发现时，使用 google_maps_reviews。
• 使用 company_insights 获取公司概况数据和公司档案补充信息。
• 使用 emails_and_contacts，通过已知域名查找联系人。
• 仅将 requests_get、requests_list 和 requests_delete 用于异步生命周期管理。
• 使用 balance_get 检查账户和账单，不要用于检索企业数据。

说明

• 此服务端支持 stdio、无状态 Streamable HTTP，以及有状态的本地 HTTP/SSE 模式。
• CLOUD_SERVICE=true 会为 HTTP 请求启用基于标头的 API 密钥解析。
• 为发布到 npm，软件包内容特意限制为运行时文件和文档。
• 本 README 中针对特定客户端的配置片段是实用模板；具体设置界面和配置键名称可能因 MCP 客户端和版本而略有不同。