Lead-generator-mcp-server

🎯 Lead Generator MCP Server

Google マップからビジネスリードを自動生成する、強力な Model Context Protocol（MCP）サーバーおよびスタンドアロンのスクレイパーです。ビジネスデータを抽出、検証、スコアリングし、B2B の営業、マーケティング、アウトリーチキャンペーンに向けて質の高いリードを特定します。

📋 目次

• 機能
• 仕組み
• インストール
• 使い方
  • スタンドアロンのスクレイパー
  • MCP サーバー
• 設定
• 出力形式
• リードスコアリングアルゴリズム
• アーキテクチャ
• 検出回避機能
• コントリビューション
• ライセンス
• 免責事項

✨ 機能

• 🔍 Google マップの自動スクレイピング - 検索クエリからビジネスデータを抽出します
• 🤖 MCP サーバーとの統合 - Model Context Protocol 経由でスクレイピング機能を公開します
• 📊 インテリジェントなリードスコアリング - ウェブサイトの有無、レビュー、評価に基づいてビジネスを評価します
• ✅ データ検証 - 電話番号とウェブサイトの URL を検証します
• 🌐 国際電話番号のフォーマット - Google の libphonenumber を使用して電話番号を標準化します
• 🎭 検出回避メカニズム - ユーザーエージェントのローテーション、ランダムな遅延、人間らしい操作
• 📈 進捗の追跡 - tqdm によるリアルタイムの進捗バー
• 💾 CSV エクスポート - リードの品質順に並べた構造化データを出力します
• 🔄 エラー復旧 - 自動再試行による堅牢なエラー処理

🎯 仕組み

┌─────────────┐     ┌──────────────┐     ┌─────────────┐     ┌──────────────┐
│   Search    │────>│ Scroll &     │────>│  Extract    │────>│  Validate &  │
│   Query     │     │ Load Results │     │  Data       │     │  Score Leads │
└─────────────┘     └──────────────┘     └─────────────┘     └──────────────┘
                                                                      │
                                                                      ▼
                                                               ┌──────────────┐
                                                               │ Export CSV   │
                                                               └──────────────┘

1. 検索：クエリを指定して Google マップに移動します
2. スクロール：スクロールして結果を動的に読み込みます（無限スクロールに対応）
3. 抽出：各ビジネスのリスティングをクリックして詳細をスクレイピングします
4. 検証：電話番号とウェブサイトを検証します
5. スコアリング：リードの品質スコア（0～100）を計算します
6. エクスポート：リードスコア順に並べて CSV に保存します

🚀 インストール

前提条件

• Python 3.8 以降
• pip（Python パッケージマネージャー）

ステップ 1：リポジトリをクローンする

git clone https://github.com/4darsh-Dev/Lead-generator-mcp-server.git
cd Lead-generator-mcp-server

ステップ 2：仮想環境を作成する

# Create virtual environment
python -m venv myenv

# Activate virtual environment
# On Linux/macOS:
source myenv/bin/activate

# On Windows:
myenv\Scripts\activate

ステップ 3：依存関係をインストールする

# Install Python packages
pip install -r requirements.txt

# Install Playwright browsers (required)
playwright install chromium

📖 使い方

1. スタンドアロンのスクレイパー（CLI）

基本的な使い方

python src/scraper.py --query "coffee shops in Seattle" --max-results 50

詳細オプション

# Visible browser mode (for debugging)
python src/scraper.py --query "beauty salons in London" --max-results 100 --visible

# Custom output filename
python src/scraper.py --query "restaurants in New York" --max-results 200 --output ny_restaurants.csv

# Complete example
python src/scraper.py \
  --query "plumbers in Boston" \
  --max-results 150 \
  --output boston_plumbers_2026.csv \
  --visible

コマンドライン引数

引数	型	必須	デフォルト	説明
--query	string	✅ はい	-	検索クエリ（例：「dentists in Chicago」）
--max-results	integer	❌ いいえ	100	スクレイピングするビジネスの最大数
--output	string	❌ いいえ	business_leads_{timestamp}.csv	出力 CSV ファイル名
--visible	flag	❌ いいえ	False	ブラウザーを可視モードで実行します（headless=False）

クエリの例

# Target businesses without websites (good for web dev services)
python src/scraper.py --query "yoga studios in Austin"

# B2B lead generation
python src/scraper.py --query "software companies in San Francisco" --max-results 300

# Local service businesses
python src/scraper.py --query "HVAC contractors in Phoenix" --max-results 150

# International search
python src/scraper.py --query "cafes in Mumbai" --max-results 100

2. MCP サーバーモード

AI アシスタントや自動化ツールと統合するには、MCP サーバーとして実行します：

python src/mcp-server.py

サーバーは http://localhost:8080 で起動し、scrape_google_maps ツールを公開します。

MCP ツールの使い方

# Example MCP tool call
result = scrape_google_maps(
    query="digital marketing agencies in Toronto",
    max_results=50
)
# Returns: List of validated business data dictionaries

⚙️ 設定

ヘッドレスモード

# In your code
scraper = GoogleMapsScraper(headless=True)  # Invisible (faster)
scraper = GoogleMapsScraper(headless=False)  # Visible (debugging)

スローモーション（デバッグ用）

# Add delays between actions (milliseconds)
scraper = GoogleMapsScraper(headless=False, slow_mo=100)

ユーザーエージェント

ユーザーエージェントは、scraper.py の USER_AGENTS リストから自動的にローテーションされます。さらに追加できます：

USER_AGENTS = [
    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36...",
    # Add your custom user agents here
]

📊 出力形式

CSV 列

列	型	説明
name	string	事業者名
category	string	事業者のカテゴリ／種類
address	string	完全な住所
phone	string	電話番号（国際形式）
phone_valid	boolean	電話番号の検証ステータス
website	string	ウェブサイトの URL
website_valid	boolean	ウェブサイトへのアクセス可否
rating	float	Google Maps の評価（星 0～5）
reviews	integer	レビュー数
lead_score	integer	算出されたリード品質スコア（0～100）

出力例

name,category,address,phone,phone_valid,website,website_valid,rating,reviews,lead_score
"Joe's Coffee Shop","Coffee shop","123 Main St, Seattle, WA","+1 206-555-0123",True,"N/A",False,4.8,342,85
"Brew & Bean","Café","456 Pike St, Seattle, WA","+1 206-555-0456",True,"https://brewbean.com",True,4.5,128,70

🎯 リードスコアリングアルゴリズム

事業者は以下に基づいて0～100のスコアで評価されます。

要素	影響	点数
ウェブサイトなし	ウェブサービスの質の高い見込み客	+20
無効なウェブサイト	ウェブサイトのサポートが必要	+15
高評価（4.5+）	品質重視で、予算がある	+10
レビューが少ない（<10）	新規事業で、マーケティングが必要	+10
レビューが多い（>100）	確立されており、リソースがある	+5

基本スコア：50 点
最大スコア：100 点

CSV の出力では、リードはスコアの高い順に自動的に並べ替えられます。

🏗️ アーキテクチャ

Lead-generator-mcp-server/
├── src/
│   ├── scraper.py           # Core scraping logic
│   ├── mcp-server.py        # MCP server wrapper
│   └── __init__.py
├── myenv/                   # Virtual environment
├── requirements.txt         # Python dependencies
├── LICENSE                  # MIT License
└── README.md               # Documentation

主なコンポーネント

• GoogleMapsScraper クラス：ブラウザー自動化を行うメインのスクレーパー
• scrape_google_maps() ツール：MCP に公開される関数
• Playwright：ブラウザー自動化フレームワーク
• Pandas：データ操作と CSV エクスポート
• phonenumbers：電話番号の検証（Google の libphonenumber）
• tqdm：進捗バー

🎭 検出回避機能

1. ユーザーエージェントのローテーション：セッションごとにランダムなユーザーエージェントを使用
2. 人間らしい遅延：1～3 秒のランダムな待機
3. 現実的なヘッダー：Accept-Language、Accept ヘッダー
4. スローモーション：操作間の遅延を設定可能
5. スクロール動作：人間のようなスムーズなスクロール
6. エラー復旧：検出された場合に適切に処理

🛠️ トラブルシューティング

よくある問題

問題：playwright._impl._errors.Error: Executable doesn't exist
解決方法：playwright install chromium を実行します

問題：結果が見つからない
解決方法：

• デバッグのため、--visible フラグを指定して実行してみます
• Google Maps の HTML 構造が変更されていないか確認します
• インターネット接続を確認します

問題：logging/argparse の ImportError
解決方法：scraper.py に以下のインポートを追加します：

import logging
import argparse
import random
import time
import re
import requests
import pandas as pd
import phonenumbers

問題：スクロール中にスクリプトが停止する
解決方法：

• --max-results の値を小さくします
• scroll_results() メソッドの max_attempts を確認します

🤝 コントリビューション

コントリビューションを歓迎します。以下の手順に従ってください。

1. リポジトリをフォークします
2. 機能ブランチを作成します（git checkout -b feature/AmazingFeature）
3. 変更をコミットします（git commit -m 'Add some AmazingFeature'）
4. ブランチにプッシュします（git push origin feature/AmazingFeature）
5. プルリクエストを作成します

開発環境のセットアップ

# Clone your fork
git clone https://github.com/YOUR_USERNAME/Lead-generator-mcp-server.git
cd Lead-generator-mcp-server

# Create virtual environment
python -m venv myenv
source myenv/bin/activate  # or myenv\Scripts\activate on Windows

# Install dev dependencies
pip install -r requirements.txt
playwright install chromium

# Run tests (if available)
pytest tests/

📄 ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細については、LICENSE ファイルをご覧ください。

Copyright (c) 2025 ADARSH MAURYA

⚠️ 免責事項

このツールは教育および研究目的のみを対象としています。このスクレーパーを使用する際は、以下を守ってください。

• ✅ Google Maps の利用規約を尊重する
• ✅ レート制限を実装する（速くスクレイピングしすぎない）
• ✅ 正当な事業目的で責任を持って使用する
• ✅ GDPR、CCPA、およびデータ保護法を遵守する
• ❌ スパムや未承諾のマーケティングに使用しない
• ❌ Google のサーバーに過剰な負荷をかけない

本ツールの誤用について、作者は一切責任を負いません。

📞 連絡先とサポート

• 作者：ADARSH MAURYA
• GitHub： @4darsh-Dev
• リポジトリ：Lead-generator-mcp-server

問題とバグ

バグを見つけましたか？機能のリクエストがありますか？Issue を作成してください。

---

⭐ 役に立った場合は、このリポジトリにスターを付けてください！

Adarsh Maurya が ❤️ を込めて作成