Batchdata Mcp (real Estate & Contact Data)

BatchData 远程 MCP 服务设置指南

• 1 简介
• 2 身份验证方式
  • 2.1 OAuth 身份验证（推荐）
  • 2.2 API 令牌身份验证（备选）
• 3 未来增强功能：OAuth 访问控制（即将推出）
• 4 OAuth 设置（推荐）
  • 4.1 先决条件
  • 4.2 Claude 设置（桌面端、网页端和移动端）
    • 4.2.1 步骤 1：添加 BatchData 连接器
    • 4.2.2 步骤 2：进行身份验证
    • 4.2.3 步骤 3：启用连接器
    • 4.2.4 步骤 4：批准首次使用工具
    • 4.2.5 在移动端使用
    • 4.2.6 后续连接
  • 4.3 Cursor 设置
  • 4.4 Claude Code 设置
  • 4.5 ChatGPT 设置（开发者模式）
    • 4.5.1 先决条件
    • 4.5.2 步骤 1：启用开发者模式
    • 4.5.3 步骤 2：创建 BatchData 连接器
    • 4.5.4 步骤 3：进行身份验证
    • 4.5.5 在 ChatGPT 中使用 BatchData 工具
    • 4.5.6 管理连接
  • 4.6 验证
• 5 API 令牌设置（备选）
  • 5.1 先决条件
  • 5.2 使用 API 令牌设置 Claude Desktop
    • 5.2.1 步骤 1：安装 Node.js 22
    • 5.2.2 步骤 2：配置 Claude Desktop
  • 5.3 自定义 MCP 客户端设置
• 6 从 API 令牌迁移到 OAuth
  • 6.1 Claude Desktop
  • 6.2 Claude Code
  • 6.3 ChatGPT
  • 6.4 迁移的优势
• 7 可用工具
  • 7.1 房产查询与详情
  • 7.2 可比房产分析
  • 7.3 房产搜索
  • 7.4 联系信息
  • 7.5 电话号码验证
  • 7.6 地址处理
• 8 故障排除
  • 8.1 OAuth 问题
  • 8.2 ChatGPT 问题
  • 8.3 API 令牌问题
  • 8.4 常见问题
  • 8.5 获取帮助

简介

本指南介绍如何使用兼容 MCP 的客户端连接到 BatchData 远程 MCP 服务。

身份验证方式

BatchData MCP 服务支持两种身份验证方式：

方式	设置复杂度	安全性	推荐对象
OAuth（推荐）	简单	高	大多数用户
API 令牌	手动配置	中等	自定义 MCP 客户端、调试

OAuth 身份验证（推荐）

OAuth 提供了简化的连接体验：

• 无需配置 API 令牌 — 只需提供服务 URL
• 基于浏览器登录 — 使用 BatchData 账户凭据进行身份验证
• 自动管理令牌 — 访问令牌会自动刷新
• 熟悉的登录体验 — 使用电子邮件/密码或 Google 登录

API 令牌认证（替代方式）

对于倾向于直接配置 API 令牌的用户，或使用不支持 OAuth 的自定义 MCP 客户端的用户：

• 需要手动获取并配置 BatchData API 令牌
• 必须将令牌作为敏感凭证进行管理和保护
• 适用于调试、自动化脚本或不支持 OAuth 的客户端

后续增强功能：OAuth 访问控制（即将推出）

我们正在为 OAuth 认证开发增强的访问控制功能：

• 权限验证 — OAuth 登录时将自动验证你的账号是否已获准使用 MCP 服务
• 集中式访问管理 — 团队所有者将能够通过 BatchData 平台，为团队成员授予或撤销 MCP 服务的访问权限

---

OAuth 设置（推荐）

前提条件

• 拥有一个凭据有效的 BatchData 账号
• 使用与 MCP 兼容的客户端（Claude Desktop/Web/Mobile、ChatGPT、Cursor、Claude Code 或类似客户端）

Claude 设置（桌面端、Web 端和移动端）

Claude 可通过桌面应用、Web 界面和移动应用支持 MCP 服务。

移动端说明：无法通过移动应用添加连接器。请先在桌面端或 Web 端添加连接器，它会自动在同一账号的移动端提供。

团队/企业说明：工作区管理员必须先将 BatchData 连接器添加到可用连接器列表中，团队成员才能进行配置。如果列表中没有该连接器，请联系管理员。

第 1 步：添加 BatchData 连接器

1. 打开 Claude（桌面端或 Web 端）
2. 前往 Settings → Connectors（或 Settings → MCP Servers）
3. 点击 Add Connector（或 Add Server）
4. 输入服务 URL：

https://mcp.batchdata.com

5. 点击 Add 或 Connect

第 2 步：认证

1. 浏览器将打开 BatchData 登录页面
2. 使用以下任一方式登录：

• 电子邮件和密码 — 输入你的 BatchData 账号凭据
• Google 登录 — 点击 Google 按钮进行认证

3. 登录成功后，你将被重定向回 Claude

第 3 步：启用连接器

添加连接器后，默认不会启用。启用一次后，该设置会被保存：

1. 打开任意聊天
2. 点击聊天输入区域中的 + 按钮（或连接器图标）
3. 在可用连接器列表中找到 BatchData
4. 将其切换为开启状态

现在，该连接器将在你的所有对话中可用。

第 4 步：批准首次使用工具

Claude 首次使用任何 BatchData 工具时，会要求你批准：

1. Claude 尝试使用工具时，会显示权限提示
2. 查看请求使用的工具和操作
3. 点击 Allow 进行批准
4. 如果想以后使用该工具时跳过审批，请选择 "Always allow"

注意：首次批准后（或选择 "Always allow" 后），后续使用工具时无需再次确认。

在移动端使用

在桌面端或 Web 端添加并认证连接器后：

• 使用同一账号打开 Claude 移动应用
• BatchData 连接器将在连接器列表中显示
• 如果尚未启用，请通过聊天输入框中的 + 按钮将其开启（设置会在设备间同步）
• 在桌面端/Web 端批准的工具使用权限也会同步到移动端
• 所有工具的使用方式都与桌面端/Web 端相同

后续连接

完成首次认证后：

• 访问令牌会被缓存，并在所有设备上自动刷新
• 除非会话过期，否则无需再次登录（通常在连续 14 天未活动后过期）
• 如果系统提示重新认证，只需通过浏览器再次登录（在桌面端或 Web 端）

Cursor 设置

1. 打开 Cursor 设置
2. 前往 MCP 配置部分
3. 点击 Add MCP Server
4. 输入服务 URL：

https://mcp.batchdata.com

5. 首次使用时，通过浏览器弹出窗口进行认证

Claude Code 设置

直接通过 CLI 添加 BatchData MCP 服务：

claude mcp add BatchData --url https://mcp.batchdata.com

首次使用时，系统会提示你通过浏览器进行身份验证。

ChatGPT 设置（开发者模式）

ChatGPT 通过开发者模式支持 MCP 服务，并提供完整的模型上下文协议客户端支持。

前提条件

• ChatGPT Plus 或 Pro 订阅
• 对于 Business/Enterprise：管理员必须在工作区设置中启用开发者模式

第 1 步：启用开发者模式

1. 打开 ChatGPT
2. 前往 设置 → 应用和连接器 → 高级设置
3. 将 开发者模式 切换为开启状态

对于 Business/Enterprise 工作区：

• 管理员必须先在 工作区设置 → 权限和角色 → 已连接数据 → 开发者模式 / 创建自定义 MCP 连接器 中启用开发者模式

第 2 步：创建 BatchData 连接器

1. 在 ChatGPT 中，前往 设置 → 连接器
2. 点击 创建
3. 输入以下详细信息：

• 连接器名称：BatchData
• MCP 服务 URL：https://mcp.batchdata.com

4. 点击 创建

第 3 步：进行身份验证

1. 创建连接器后，ChatGPT 会提示你进行身份验证
2. 浏览器将打开 BatchData 登录页面
3. 使用以下任一方式登录：

• 电子邮件和密码 — 输入你的 BatchData 账户凭据
• Google 登录 — 点击 Google 按钮进行身份验证

4. 成功登录后，你将被重定向回 ChatGPT
5. BatchData 连接器现已可以使用

在 ChatGPT 中使用 BatchData 工具

连接后，你可以在对话中使用 BatchData 工具：

1. 开始新聊天
2. 点击 + 按钮，然后从 更多 菜单中选择你的连接器
3. 或者，从 加号菜单 中选择 开发者模式，然后选择 BatchData
4. 提出与房产相关的问题 — ChatGPT 将使用相应的工具

提示词示例：

• “查询位于 123 Main Street, Los Angeles, CA 的房产”
• “查找 456 Oak Avenue 的可比房产”
• “跳查 789 Pine Road, Miami, FL 房产所有者”

管理连接

• 断开连接：前往 设置 → 连接器，点击 BatchData，然后断开连接
• 重新连接：点击连接器并重新进行身份验证
• 会话过期：如果会话过期（通常在 14 天后），系统会提示你重新连接

验证

连接后，只需询问房产数据或跳查信息，大模型便会自动使用 BatchData 工具。

提示词示例：

• “查询位于 123 Main Street, Los Angeles, CA 的房产”
• “跳查 456 Oak Avenue, Miami, FL 房产所有者”
• “查找 789 Pine Road, Austin, TX 的可比房产”
• “搜索 Miami, FL 的空置房产”
• “验证此电话号码：555-123-4567”
• “验证并规范化此地址：100 main st los angeles ca”
• “获取 200 Park Avenue, New York, NY 的坐标”

Claude 或 ChatGPT 会识别意图，并使用相应的 BatchData 工具获取信息。

---

API 令牌设置（替代方案）

在以下情况下使用此方法：

• 你的 MCP 客户端不支持 OAuth
• 你需要调试或自动化 MCP 服务连接
• 你倾向于显式管理令牌

前提条件

• 你的 BatchData API 令牌（从 BatchData Web App 获取）
• 与 MCP 兼容的客户端
• Node.js 22+（用于 Claude Desktop）

使用 API 令牌设置 Claude Desktop

第 1 步：安装 Node.js 22

Claude Desktop 内置的 Node.js 版本过旧。请单独安装 Node.js 22：

macOS/Linux：

# Install Volta (Node.js version manager) curl https://get.volta.sh | bash # Restart terminal, then install Node.js 22 volta install node@22 # Find your username for the config below whoami

Windows：

从 nodejs.org 下载并安装 Node.js 22.x LTS

步骤 2：配置 Claude Desktop

1. 打开 Claude Desktop
2. 前往 Settings > Developer > Edit Config
3. 添加以下配置：

macOS 配置：

{ "mcpServers": { "BatchData": { "command": "/Users/YOUR_USERNAME/.volta/bin/npx", "args": [ "-y", "mcp-remote", "https://mcp.batchdata.com", "--header", "Authorization:${AUTH_HEADER}" ], "env": { "AUTH_HEADER": "Bearer YOUR_API_TOKEN_HERE" } } } }

Linux 配置：

{ "mcpServers": { "BatchData": { "command": "/home/YOUR_USERNAME/.volta/bin/npx", "args": [ "-y", "mcp-remote", "https://mcp.batchdata.com", "--header", "Authorization:${AUTH_HEADER}" ], "env": { "AUTH_HEADER": "Bearer YOUR_API_TOKEN_HERE" } } } }

Windows 配置：

{ "mcpServers": { "BatchData": { "command": "C:\\Program Files\\nodejs\\npx.cmd", "args": [ "-y", "mcp-remote", "https://mcp.batchdata.com", "--header", "Authorization:${AUTH_HEADER}" ], "env": { "AUTH_HEADER": "Bearer YOUR_API_TOKEN_HERE" } } } }

4. 将 YOUR_USERNAME 替换为你的实际用户名
5. 将 YOUR_API_TOKEN_HERE 替换为你的 BatchData API Token
6. 保存文件并重启 Claude Desktop

自定义 MCP 客户端设置

用于自定义 MCP 客户端实现：

连接详情：

设置	值
服务 URL	https://mcp.batchdata.com
传输方式	Streamable HTTP
身份验证	通过 Authorization 标头使用 Bearer token

配置示例：

{ "server_url": "https://mcp.batchdata.com", "headers": { "Authorization": "Bearer YOUR_API_TOKEN_HERE" } }

使用 npx：

npx mcp-remote https://mcp.batchdata.com --header "Authorization:Bearer YOUR_API_TOKEN_HERE"

---

从 API Token 迁移到 OAuth

如果你之前使用 API Token 方式设置了 BatchData，现在想切换到 OAuth，以获得更简单的体验，请按照以下步骤操作：

Claude Desktop

1. 打开 Claude Desktop
2. 前往 Settings → Developer → Edit Config
3. 移除现有的 BatchData 配置（包含 command、args 和 env 的整个代码块）
4. 保存并关闭配置文件
5. 按照 Claude 设置（桌面端、网页端和移动端） 中的说明，通过界面添加连接器
6. 按提示使用你的 BatchData 账户进行身份验证

之前（API Token）：

{ "mcpServers": { "BatchData": { "command": "/Users/YOUR_USERNAME/.volta/bin/npx", "args": ["-y", "mcp-remote", "https://mcp.batchdata.com", "--header", "Authorization:${AUTH_HEADER}"], "env": { "AUTH_HEADER": "Bearer YOUR_API_TOKEN" } } } }

之后（OAuth）： 通过界面配置 — 无需编辑 JSON。

Claude Code

1. 移除现有配置：

claude mcp remove BatchData

2. 使用 OAuth 重新添加：

claude mcp add BatchData --url https://mcp.batchdata.com

3. 按提示通过浏览器进行身份验证

ChatGPT

如果你之前使用 API Token 作为变通方案，只需：

1. 从 Settings → Connectors 中移除现有的 BatchData 连接器
2. 按照 ChatGPT 设置 中的说明创建新的连接器
3. 使用你的 BatchData 账户进行身份验证

迁移的优势

方面	API Token	OAuth
设置	手动编辑 JSON	简单的界面操作
Token 管理	手动轮换	自动刷新
安全性	Token 存储在配置文件中	Token 由客户端管理
多设备	逐台设备配置	在设备间同步

---

可用工具

连接后，BatchData MCP Server 将提供以下工具：

房产查询与详情

工具	描述
lookup_property	按 ID、地址或地块编号获取详细房产信息

可比房产分析

工具	描述
comparable_property_count	获取可比房产数量及汇总指标
comparable_property_preview	快速预览前 10 个可比房产及摘要字段
comparable_property_page	分页访问完整的可比房产详情（支持基于偏移量和游标的分页）
comparable_property	⚠️ 已弃用 — 一次性返回所有可比房产

房产搜索

工具	描述
search_properties_count	获取符合搜索条件的房产数量及快速列表细分
search_properties_preview	快速预览前 10 个匹配的房产
search_properties_page	分页搜索房产并获取完整详情（支持基于偏移量和游标的分页）

联系信息

工具	描述
skip_trace_property	按地址或地块编号获取房产所有者及联系信息

电话验证

工具	描述
verify_phone	获取完整验证详情，包括可接通性、DNC 状态、运营商及 TCPA 诉讼人状态
check_dnc_status	仅检查勿致电状态
check_tcpa_status	仅检查 TCPA 诉讼人状态

地址处理

工具	描述
verify_address	将地址格式整理为符合 USPS 规范
geocode_address	根据地址获取坐标
reverse_geocode_address	根据纬度/经度坐标获取地址

---

故障排除

OAuth 问题

问题	解决方案
登录时浏览器未打开	确保允许弹出窗口。检查默认浏览器是否设置正确。
登录页面显示“Session expired”	移除并重新添加连接器，然后再次进行身份验证。
出现“Too many login attempts”错误	等待 15 分钟后再试。
Google Sign-In 无法使用	确保允许弹出窗口，并尝试改用电子邮件/密码登录。
登录后连接失败	检查网络连接。重定向回 MCP 客户端的步骤可能失败了。尝试移除并重新添加连接器。

ChatGPT 问题

问题	解决方案
无法创建连接器	确保已在 Settings → Apps & Connectors → Advanced settings 中启用 Developer Mode。
找不到 Developer Mode 开关	对于 Business/Enterprise，工作区管理员必须先在 Workspace Settings 中启用此功能。
身份验证失败	确保允许 http://chatgpt.com 的弹出窗口。尝试断开连接器并重新连接。
未使用工具	在提示词中明确说明：“使用 BatchData 连接器来……”。提示前，先通过 + 按钮添加连接器。
连接器无响应	前往 Settings → Connectors → BatchData → Refresh 以更新元数据。服务可能暂时不可用。
调用了错误的工具	指定：“不要使用内置浏览功能或其他工具；只使用 BatchData 连接器。”

API Token 问题

问题	解决方案
401 Unauthorized	确认 API token 正确且未过期。
403 Forbidden	确保 token 在 BatchData Web App 中拥有所需端点的权限。
Node.js 路径错误	运行 which npx（macOS/Linux）确认 npx 路径存在，或检查安装路径（Windows）。
配置未加载	保存配置文件后，重启 MCP 客户端。

一般问题

问题	解决方案
未显示工具	确认 MCP 服务已在客户端的扩展列表中启用。
SkipTracing 返回 403	管理员必须为团队启用 SkipTracing v3，且 token 需要具备相应权限。
响应缓慢	检查网络连接。该服务会代理对 BatchData APIs 的请求。

获取帮助

• API Token 问题：登录 BatchData Web App 管理服务端 token
• 权限问题：联系 BatchData 团队管理员
• 技术问题：联系 BatchData 支持团队

---

© BatchData 2025