Lead-generator-mcp-server

🎯 潜在客户生成 MCP 服务

功能强大的 Model Context Protocol（MCP）服务和独立爬虫，可从 Google Maps 自动生成商业潜在客户。提取、验证并评分商业数据，为 B2B 销售、营销和推广活动筛选高质量潜在客户。

📋 目录

• 功能
• 工作原理
• 安装
• 使用方法
  • 独立爬虫
  • MCP 服务
• 配置
• 输出格式
• 潜在客户评分算法
• 架构
• 反检测功能
• 贡献
• 许可证
• 免责声明

✨ 功能

• 🔍 自动抓取 Google Maps - 根据搜索查询提取商业数据
• 🤖 MCP 服务集成 - 通过 Model Context Protocol 提供抓取功能
• 📊 智能潜在客户评分 - 根据网站存在情况、评论和评分为商家评分
• ✅ 数据验证 - 验证电话号码和网站 URL
• 🌐 国际电话号码格式化 - 使用 Google 的 libphonenumber 统一电话号码格式
• 🎭 反检测机制 - 轮换用户代理、随机延迟、模拟人类行为
• 📈 进度跟踪 - 使用 tqdm 实时显示进度条
• 💾 CSV 导出 - 按潜在客户质量排序的结构化数据输出
• 🔄 错误恢复 - 通过自动重试实现稳健的错误处理

🎯 工作原理

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

1. 搜索：使用查询访问 Google Maps
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	字符串	✅ 是	-	搜索查询（例如，“dentists in Chicago”）
--max-results	整数	❌ 否	100	要抓取的商家数量上限
--output	字符串	❌ 否	business_leads_{timestamp}.csv	输出 CSV 文件名
--visible	标志	❌ 否	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 服务模式

作为 MCP 服务运行，以便与 AI 助手和自动化工具集成：

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. User-Agent 轮换：每个会话随机使用 User-Agent
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. Fork 此仓库
2. 创建功能分支（git checkout -b feature/AmazingFeature）
3. 提交你的更改（git commit -m 'Add some AmazingFeature'）
4. 推送到该分支（git push origin feature/AmazingFeature）
5. 发起 Pull Request

开发环境设置

# 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 文件。

Copyright (c) 2025 ADARSH MAURYA

⚠️ 免责声明

此工具仅用于教育和研究目的。使用此爬虫时：

• ✅ 遵守 Google Maps 服务条款
• ✅ 实施速率限制（不要爬取过快）
• ✅ 仅将工具用于合法的商业目的
• ✅ 遵守 GDPR、CCPA 和数据保护法律
• ❌ 不得用于垃圾信息或未经请求的营销
• ❌ 不得让 Google 的服务器过载

作者不对滥用此工具的行为负责。

📞 联系与支持

• 作者：ADARSH MAURYA
• GitHub： @4darsh-Dev
• 仓库：Lead-generator-mcp-server

问题与错误

发现错误？有功能请求？提交问题

---

⭐ 如果你觉得这个仓库有帮助，请为其点星！

由 Adarsh Maurya 用 ❤️ 制作