Outscraper Mcp Server

Outscraper MCP

Outscraper の公式 MCP サーバーです。

AI エージェントを Outscraper に接続し、ビジネスの検索、Google マップの情報取得、企業および連絡先情報の補完、レビュー分析、検索、構造化されたウェブ情報の抽出を行えます。

おすすめの用途

• 地域のビジネスの見込み顧客開拓とリード獲得
• Google マップの場所、写真、レビューに関する情報取得
• 既知のドメインを使った企業および連絡先情報の補完
• ポーリングを伴う非同期データ収集ワークフロー
• 単一ページからの構造化情報の抽出

あまり適さない用途

• ブラウザーの自動化や複数段階にわたる UI 操作
• 汎用的な OAuth ベースの SaaS 連携
• Outscraper のデータ範囲外にある任意のドキュメント検索
• ブラウザーの永続的なセッションが必要なウェブサイトのクロール

よくあるワークフロー

• businesses_search でビジネスを見つけ、選んだレコードを businesses_get で補完する
• Google マップで場所を検索し、レビューや写真を取得して評判を分析する
• 企業ドメインの情報を補完し、メールアドレスを検証して、連絡先の網羅状況を確認する
• 非同期ジョブを送信し、requests_get でポーリングする
• ai_scraper でページから構造化データを抽出する

本番環境に対応した MCP ツールを提供します。対象は次のとおりです。

• ビジネスの検索と情報補完
• Google マップの場所、レビュー、写真、チェーンの検出
• 企業情報、メールアドレス、メールアドレスの検証、電話番号の補完
• Google 検索と Google 画像検索
• Yellow Pages、Booking、Yelp、Tripadvisor、Trustpilot、Indeed のデータ
• アカウント残高の確認と非同期リクエストのライフサイクル管理

このサーバーは、stdio と HTTP のトランスポート、npm ベースのインストール、ホスト側でのヘッダーまたは URL による認証をサポートし、MCP クライアントおよびエージェント向けに正規化された structuredContent の結果形式を提供します。

概要

この MCP サーバーは、Outscraper のデータソースと情報補完ワークフローを MCP 対応クライアントに提供します。

次の用途向けに設計されています。

• ビジネスと場所の検索
• Google マップのレビューと写真の取得
• 連絡先と企業情報の補完
• 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 クライアントには、次のように設定します。

• コマンド：npx
• 引数：["-y", "outscraper-mcp"]
• 環境変数：OUTSCRAPER_API_KEY=YOUR_API_KEY

タスク指向のワークフロー、コピーして使える例、およびエージェントスキルの例については、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 が優先されます。

インストール

この MCP サーバーの利用には、npm からの使用を推奨します。

npm から実行する

npx -y outscraper-mcp

MCP クライアントの設定またはシェル環境で 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 コネクター

このサーバーをリモート MCP コネクターとして ChatGPT に接続する場合、最もシンプルなホスト形式は次のとおりです。

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

推奨セットアップ：

1. 実際のドメインまたはリバースプロキシの背後で、サーバーを HTTPS 経由でデプロイします。
2. CLOUD_SERVICE=true でホストモードを有効にします。
3. コネクターがカスタム認証ヘッダーを付与できない場合は、URL 認証ルートを使用します。
4. カスタムヘッダーを使用できるサーバー間クライアントでは、ヘッダー認証を優先してください。

一般的なコネクター設定値：

• 名前：Outscraper MCP
• 説明：ビジネスの発見、Google マップのデータ、エンリッチメント、検索、AI スクレイピング
• MCP サーバー URL：https://your-domain.example/v1/mcp/YOUR_API_KEY
• 認証：なし

注意事項：

• 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 でリッスンします
• 上流 API のベース URL として https://api.outscraper.com を使用します

エンドポイント：

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" を使用してください。

1 件のビジネスを取得する

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

Google Maps を検索する

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

Google Maps のレビューを取得する

{
  "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 Maps の写真を取得する

{
  "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. というエラーが発生する場合があります。この動作は MCP レイヤー内だけでなく、実際の API に対しても再現されました。
• ai_scraper は、JSON 本文を指定した POST で最も適切に機能します。実環境での検証では、POST は prompt と schema を安定して受け付けましたが、schema や query_schema を使用する GET の形式では、同じ動作が一貫して確認できませんでした。
• Outscraper の OpenAPI の例と実際の API の動作が異なる場合は、実際のエンドポイントの動作を信頼できる情報源として扱ってください。
• businesses_search は、現在の /businesses の OpenAPI 仕様がリクエスト本文ベースであり、実環境での検証でも安定した非同期形式のワークフローであると確認できなかったため、ここでは同期 MCP ツールとして公開しています。
• execution_mode="auto" はヒューリスティックに基づいています。実用的なデフォルトを選択する設計ですが、決定的な動作が必要な場合は、sync または async を明示的に使用してください。
• HTTP のホストモードで CLOUD_SERVICE=true を使用する場合は、正しい認証ヘッダーが必要です。stdio モードでは引き続き、プロセス環境に OUTSCRAPER_API_KEY を設定する必要があります。
• chain_info は、Outscraper が現在、独立した chain info エンドポイントを記載していないため、google-maps-search における、ドキュメントに記載された ai_chain_info エンリッチメントを使用して実装されています。
• Outscraper が専用の BuiltWith エンドポイントを現在ドキュメントに記載していないため、builtwith はツールとして公開されていません。

ツール選択に関する注意

• フィルターとカーソルによるページネーションを使ってビジネスを構造化検索する場合は、businesses_search を使用してください。
• 具体的なビジネス ID がすでにわかっている場合は、businesses_get を使用してください。
• 人間が入力した検索クエリを使って Google Maps 形式の場所を検索する場合は、google_maps_search を使用してください。
• 場所の検索ではなく、レビューのデータが必要な場合は、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 に記載しているクライアント固有の設定例は実用的なテンプレートです。正確な設定 UI や設定キー名は、MCP クライアントやバージョンによって多少異なる場合があります。