Hubertino: Google Maps leads

Hubertino MCP 服务：为 Claude、Cursor 和其他 AI Agent 提供 Google Maps 潜在客户

@hubertino/mcp-server 可将任何 Model Context Protocol 客户端（Claude Desktop、Claude Code、Cursor、VS Code，……）连接到 Hubertino，这是一款 Google Maps 潜在客户抓取工具。向助手询问“奥斯汀有邮箱的牙医”。它会启动抓取任务，等待任务完成，然后以表格或 CSV/XLSX 文件的形式提供潜在客户。

它封装了 Hubertino 经过身份验证的公开 REST API（文档），并使用你自己的 API 密钥和额度。

你将获得

每条潜在客户信息对应一家 Google Maps 商家。只会返回有值的字段：

• 联系信息：名称、类别、电话、网站，以及在商家自有网站上找到的邮箱（enrichWebsite）。
• **社交资料：**Facebook、Instagram、LinkedIn、X、YouTube（enrichLinks）。
• **位置：**地址、城市、州、邮政编码、国家/地区代码，以及 Google Maps 链接 / 地点 ID。
• **口碑：**评分、评价数、商家状态。
• **其他字段（为节省上下文，精简结果中不包含）：**坐标、营业时间、价格范围、服务选项，以及下单 / 预订 / 菜单链接。使用 get_results 的 detail: "full" 获取，或在 download_export 文件中查看。

工具

工具	功能	API 调用
start_scrape	针对 categories × locations 启动抓取任务。会消耗额度。	POST /api/v1/scrapes
get_scrape	返回状态、进度、预留和已扣额度，以及包含邮箱、电话等信息的行数。	GET /api/v1/scrapes/{id}
wait_for_scrape	持续轮询，直到抓取完成或超时（默认 50 s）。发送进度通知。	GET /api/v1/scrapes/{id}
list_scrapes	列出你最近的抓取任务，可按状态筛选。	GET /api/v1/scrapes
get_results	以精简 JSON 格式分页返回潜在客户行。选项：withEmailOnly、fields、detail。	GET /api/v1/scrapes/{id}/results
download_export	将已完成的抓取任务保存到你的电脑，格式为 .xlsx 或 .csv。	GET /api/v1/scrapes/{id}/export

此外还有一个提示词 build_lead_list，可针对某种业务类型和区域运行整个工作流。

start_scrape 使用与 API 相同的输入和限制：

输入	类型	说明
categories	string[]	必填。要搜索的内容，例如 ["dentist"]。1–1,000 项，每项 1–120 个字符。
locations	string[]	必填。城市、地区或邮政编码。请包含国家/地区，例如 "Austin, TX, United States"。1–10,000 项。
maxResults	integer	必填。每次搜索（每个类别 × 地点组合）的最多地点数，1–500。
country	string	可选的 Google 版本代码（us、gb、de、lt，……共 32 个代码）。若省略，则根据地点推断。
enrichWebsite	boolean	默认值为 true。访问每家商家的网站以查找邮箱。不额外消耗额度。
enrichLinks	boolean	默认值为 true。收集社交资料和下单 / 预订链接。不额外消耗额度。

一次抓取最多运行 2,000 次搜索（categories.length × locations.length）。

要求

• Node.js 20 或更高版本（npx 必须位于 MCP 客户端使用的 PATH 中）。
• Hubertino 账户和 API 密钥。新账户可获得 100 个免费额度，所有套餐（包括免费套餐）均包含 API。
  1. 在 hubertino.com 注册。
  2. 打开 设置（/dashboard/settings）并创建 API 密钥。密钥以 hub_live_ 开头，且只会显示一次，因此请立即复制。

安装

所有客户端的配置方式都相同：设置环境变量 HUBERTINO_API_KEY，然后运行 npx -y @hubertino/mcp-server。将 hub_live_your_key_here 替换为你的密钥。

Claude Desktop

打开 Settings → Developer → Edit Config。这会打开 claude_desktop_config.json，在 macOS 上的路径为 ~/Library/Application Support/Claude/claude_desktop_config.json，在 Windows 上的路径为 %APPDATA%\Claude\claude_desktop_config.json。添加：

{
  "mcpServers": {
    "hubertino": {
      "command": "npx",
      "args": ["-y", "@hubertino/mcp-server"],
      "env": {
        "HUBERTINO_API_KEY": "hub_live_your_key_here"
      }
    }
  }
}

重启 Claude Desktop。随后，Hubertino 工具会显示在工具菜单中。

可以使用 npm run bundle 构建一键安装包（hubertino-mcp.mcpb），然后在 Claude Desktop 中打开。它会通过表单询问密钥，因此无需编辑任何 JSON。

Claude Code

claude mcp add hubertino -e HUBERTINO_API_KEY=hub_live_your_key_here -- npx -y @hubertino/mcp-server

添加 --scope user，即可在每个项目中使用。运行 claude mcp list 检查连接状态。

Cursor

将服务添加到 ~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（单个项目）：

{
  "mcpServers": {
    "hubertino": {
      "command": "npx",
      "args": ["-y", "@hubertino/mcp-server"],
      "env": {
        "HUBERTINO_API_KEY": "hub_live_your_key_here"
      }
    }
  }
}

VS Code（GitHub Copilot 代理模式）

将以下内容添加到 .vscode/mcp.json。VS Code 会提示输入密钥并安全地保存：

{
  "inputs": [
    { "type": "promptString", "id": "hubertino-key", "description": "Hubertino API key (hub_live_...)", "password": true }
  ],
  "servers": {
    "hubertino": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@hubertino/mcp-server"],
      "env": { "HUBERTINO_API_KEY": "${input:hubertino-key}" }
    }
  }
}

其他客户端 / 从源代码运行

任何能够启动 stdio 服务的 MCP 客户端都可以使用。从代码库运行：

git clone https://github.com/hubertino-app/hubertino-mcp.git
cd hubertino-mcp && npm install && npm run build
# then point your client at:  node /absolute/path/to/hubertino-mcp/dist/index.js

配置

变量	必填	默认值	用途
HUBERTINO_API_KEY	是	无	你的 hub_live_... 密钥。如果缺少此项，服务仍会启动，并由每个工具说明如何设置。
HUBERTINO_API_URL	否	https://hubertino.com	API 基础 URL。也支持 https://hubertino.com/api/v1。仅接受 https://，localhost 除外。
HUBERTINO_DOWNLOAD_DIR	否	~/Downloads，否则为临时目录	download_export 保存文件的位置。

提示词示例

• “查找德克萨斯州奥斯汀的牙医及其电子邮件地址。每次搜索 100 个就够了。”
• “整理一份英国利兹和约克的水管工与电工名单，然后保存为 CSV 文件。”
• “抓取以下邮政编码区域的屋顶承包商：78701、78702、78703。只显示有电子邮件地址和网站的商家。”
• “我最近一次抓取的进度如何？”
• “显示我的咖啡馆抓取结果中的第 2 页：仅显示名称、电话和 Instagram。”
• “我已完成的抓取中，哪个结果最多？将其下载为 Excel 文件。”

典型运行如下：

start_scrape     {"categories":["dentist"],"locations":["Austin, TX, United States"],"maxResults":100}
  -> {"id":"6f1c…","status":"queued","credits":"Reserved 100 credits … the rest is refunded automatically.", …}
wait_for_scrape  {"scrapeId":"6f1c…"}
  -> {"status":"done","resultCount":…,"creditsCharged":…,"coverage":{"total":…,"email":…}, …}
get_results      {"scrapeId":"6f1c…","withEmailOnly":true,"limit":50}
  -> {"total":…,"returned":…,"hasMore":true,"nextOffset":50,"rows":[{"name":"…","phone":"…","email":"…"}, …]}
download_export  {"scrapeId":"6f1c…","format":"csv"}
  -> {"path":"/Users/you/Downloads/hubertino-6f1c….csv","bytes":…}

积分、限制和错误

• 1 个积分 = 1 条已交付商家数据。 抓取开始时，Hubertino 会预留 categories × locations × maxResults 个积分，最多不超过你的余额。抓取完成后，只会收取实际交付行数对应的积分，其余积分会退还。如果你的余额低于最坏情况下所需的积分，抓取仍会运行，但余额用完后就会停止。请参阅定价。
• **速度：**一次抓取需要几分钟。运行期间即可读取行（partial: true）。每行的 _status 按 found → extracted → enriched 变化。
• **速率限制：**每个账户每 5 分钟最多发起 12 次新抓取。状态、结果和导出调用不受速率限制。
• 页面大小：get_results 每次调用最多读取 1,000 行（默认 50 行）。为保护模型的上下文窗口，如果某个页面无法放入单次工具响应（约 50,000 个字符），内容会被截断，并设置 trimmed: true；请从 nextOffset 继续分页，使用 fields 请求更少的列，或使用 download_export 获取全部内容。
• 长时间抓取：get_scrape 和 wait_for_scrape 最多返回 25 个类别/位置；对于更长的列表，会添加 categoriesTotal / locationsTotal。即使 API 响应缓慢，wait_for_scrape 的运行时间也不会比 timeoutSeconds 多出约 8 秒以上。
• **导出：**只有状态为 done 时才可用。

错误会作为工具错误返回，并附带后续操作，因此助手可以恢复操作或告诉你该怎么做：

HTTP	含义	工具提示
400	输入无效	API 会指出有问题的字段
401	缺少/无效的密钥	检查 HUBERTINO_API_KEY；在 Settings 中创建或轮换密钥
402	积分不足	未扣除任何积分；请前往 /dashboard/billing 充值
403	请求被拒绝（例如，邮箱未验证）	API 返回的提示
404	未知抓取 ID	使用 list_scrapes 检查 ID
409	尚未完成	使用 wait_for_scrape 等待，然后重试
410	结果已不再存储	发起新的抓取
429	触发速率限制	等几分钟后再发起抓取
5xx	暂时不可用	一分钟后重试
timeout / network	Hubertino 未响应	稍后重试

如果启动抓取时出现超时、网络错误或 5xx 错误，抓取仍可能已经创建。此时 start_scrape 会提示先检查 list_scrapes，再决定是否重新启动，以免同一次抓取运行并扣费两次。

安全与隐私

• 你的 API 密钥保留在 MCP 客户端的配置中，并且只会通过 HTTPS 以 Bearer 标头发送到 Hubertino API。服务端绝不会记录该密钥或在响应中返回该密钥。请勿将密钥粘贴到聊天中。
• 服务端只会调用上文列出的经过身份验证的 /api/v1 端点。它不会发起其他网络调用，也不会自行抓取数据。
• download_export 只会在所选文件夹中写入 hubertino-<scrape id prefix>.csv / .xlsx 文件，并且绝不会覆盖已有文件。
• 请合法使用潜在客户数据。遵守适用于你和你联系对象的隐私与反垃圾邮件规则（例如 GDPR、PECR、CAN-SPAM）。

开发

npm install
npm run build        # compile to dist/
npm test             # type-check and run the node:test suites (mocked fetch; no network)
npm run smoke        # spawn dist/index.js over stdio and list tools (set HUBERTINO_API_KEY for a live read-only call)
npm run bundle       # build hubertino-mcp.mcpb (Claude Desktop / Smithery bundle)

# optional: compare mirrored limits with a local checkout of the Hubertino app
HUBERTINO_APP_DIR=/path/to/hubertino/app npm test

发布步骤见 PUBLISHING.md。

链接

• API 文档：https://hubertino.com/docs
• 定价：https://hubertino.com/pricing
• Google Maps 抓取工具：https://hubertino.com/google-maps-scraper
• 联盟计划（持续返佣 25%）：https://hubertino.com/partners

许可证

MIT © Hubertino MB