BatchData MCP Server

BatchData - 房地产数据 - MCP 服务

一个与 BatchData.io 全面的房产和地址 API 集成的模型上下文协议（MCP）服务。此服务可访问房产数据、地址验证、跳过追踪、地理编码和高级房产搜索功能。

功能

地址操作

• verify-address：使用 USPS 验证来验证和标准化地址
• autocomplete-address：在输入时获取智能地址建议
• geocode-address：将地址转换为纬度/经度坐标
• reverse-geocode：将坐标转换回可读地址

房产操作

• lookup-property：通过地址或 APN（评估员地块编号）获取详细的房产信息
• search-properties：使用全面的筛选条件进行高级房产搜索
• search-properties-by-boundary：使用边界框或半径进行地理边界搜索
• count-properties：获取符合特定条件的房产数量（轻量级操作）

安装

通过 Smithery 安装

如需通过 Smithery 自动为 Claude Desktop 安装 batchdata-mcp-real-estate：

npx -y @smithery/cli install @zellerhaus/batchdata-mcp-real-estate --client claude

手动安装

1. 将此 MCP 服务克隆或下载到本地计算机

2. 安装依赖项：

   cd batchdata-mcp-real-estate
   npm install
   

3. 配置 API 密钥：

   • 从 BatchData Settings 获取 API 密钥，或在此注册。
   • 在项目根目录中创建或更新 .env 文件：

   BATCHDATA_API_KEY=your_actual_api_key_here
   

4. 构建 TypeScript 项目：

   npm run build
   

5. 测试服务：

   npm start
   

快速设置

使用自动化设置脚本：

Linux/macOS：

chmod +x setup.sh && ./setup.sh

Windows：

setup.bat

Docker 支持

使用 Docker 快速开始

1. 构建并测试 Docker 容器：

   chmod +x docker-manage.sh
   ./docker-manage.sh test
   

2. 使用 Docker Compose 运行：

   ./docker-manage.sh run
   

3. 查看日志：

   ./docker-manage.sh logs
   

Docker 管理命令

docker-manage.sh 脚本提供了便捷的命令：

• build：构建 Docker 镜像
• run：使用 docker-compose 启动
• stop：停止服务
• logs：查看服务日志
• test：构建并测试服务
• clean：清理 Docker 资源
• run-direct：直接使用 Docker 运行（用于测试）

手动使用 Docker

构建镜像：

docker build -t batchdata-mcp-server:latest .

使用环境文件运行：

docker run --rm --env-file .env batchdata-mcp-server:latest

使用 Docker Compose 运行：

docker-compose up -d

Docker 功能

• 多阶段构建，优化镜像大小
• 非 root 用户，增强安全性
• 健康检查，用于监控
• 资源限制和日志配置
• 适用于生产环境，并具备适当的信号处理

开发命令

• 构建：npm run build - 将 TypeScript 编译为 JavaScript
• 启动：npm start - 运行编译后的 JavaScript 服务
• 开发：npm run dev - 使用一条命令完成构建和运行
• 清理：npm run clean - 删除编译后的 JavaScript 文件

Claude Desktop 配置

如需在 Claude Desktop 中使用此 MCP 服务，请将以下内容添加到 Claude 配置文件中：

macOS

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "batchdata": {
      "command": "node",
      "args": ["/path/to/batchdata-mcp-real-estate/batchdata_mcp_server.js"],
      "env": {
        "BATCHDATA_API_KEY": "your_api_key_here"
      }
    }
  }
}

Windows

编辑 %APPDATA%\Claude\claude_desktop_config.json：

{
  "mcpServers": {
    "batchdata": {
      "command": "node",
      "args": ["C:\\path\\to\\batchdata-mcp-real-estate\\batchdata_mcp_server.js"],
      "env": {
        "BATCHDATA_API_KEY": "your_api_key_here"
      }
    }
  }
}

Claude Desktop 的 Docker 配置

如果通过 Docker 运行，可以配置 Claude Desktop 使用容器化服务：

{
  "mcpServers": {
    "batchdata": {
      "command": "docker",
      "args": ["exec", "-i", "batchdata-mcp-server", "node", "batchdata_mcp_server.js"],
      "env": {
        "BATCHDATA_API_KEY": "your_api_key_here"
      }
    }
  }
}

可用工具

地址工具

• verify-address - USPS 地址验证与标准化
• autocomplete-address - 智能地址建议
• geocode-address - 将地址转换为坐标
• reverse-geocode - 将坐标转换为地址

房产工具

• lookup-property - 按地址/APN 查询详细房产数据
• search-properties - 高级筛选房产搜索
• search-properties-by-boundary - 地理区域搜索
• count-properties - 房产数量查询

使用示例

统计 Phoenix 的房产数量

I need to count single-family homes in Phoenix, AZ between $250,000 and $600,000

查找可比房产

Find properties similar to 2800 N 24th St, Phoenix, AZ 85008 within 1 mile

验证地址

Verify this address: 2800 N 24th St, Phoenix, Arizona 85008

API 速率限制

BatchData.io 对各端点的速率限制如下：

• 地址验证：最多 5,000 个（每批建议 1,000 个）
• 地址地理编码：最多 90 个（每批建议 75 个）
• 房产搜索：最多 1,000 个请求
• 房产查询：标准 API 限制

环境变量

变量	描述	必填
BATCHDATA_API_KEY	您的 BatchData.io API 密钥	是

错误处理

该服务包含全面的错误处理机制，涵盖：

• 无效的 API 密钥
• 网络请求失败
• 格式错误的请求
• 超出 API 速率限制
• 无效的参数组合

依赖项

• @modelcontextprotocol/sdk：核心 MCP 框架
• zod：运行时类型验证
• dotenv：环境变量加载
• typescript：TypeScript 编译器
• @types/node：Node.js 类型定义

贡献

请参阅 CONTRIBUTING.md，了解开发环境设置和指南。

许可证

MIT 许可证 - 详情请参阅 LICENSE。

支持

• BatchData API：文档 | 控制面板
• MCP 协议：文档
• 问题：GitHub Issues

房地产专业人士和开发者：此 MCP 服务可让 Claude 通过自然语言查询直接访问全面的房产数据、验证地址并执行高级房产搜索。