Zillow Real Estate Data

Zillow MCP 服务

一个模型上下文协议（MCP）服务，使用 Python 和 FastMCP 构建，可实时访问 Zillow 房地产数据。

功能

• 🏠 房产搜索：按位置、价格范围和房产特征搜索房产
• 💰 房产详情：获取特定房产的详细信息
• 📊 Zestimate 估值：访问 Zillow 专有的房屋估值数据
• 📈 市场趋势：查看任意地点的房地产市场趋势
• 🧮 房贷计算器：根据各种输入计算房贷还款额
• 🔍 健康检查：验证 API 连通性并监控性能

安装

先决条件

• Python 3.8 或更高版本
• Zillow Bridge API 密钥（发送邮件至 [email protected] 申请访问权限）

设置

1. 克隆此仓库：

   git clone https://github.com/yourusername/zillow-mcp-server.git
   cd zillow-mcp-server
   

2. 安装依赖项：

   pip install -r requirements.txt
   

3. 创建包含 Zillow API 密钥的 .env 文件：

   ZILLOW_API_KEY=your_zillow_api_key_here
   

运行服务

使用选项运行服务：

# Standard stdio mode (for Claude Desktop)
python zillow_mcp_server.py

# HTTP server mode (for remote access)
python zillow_mcp_server.py --http --port 8000

# Debug mode for more verbose logging
python zillow_mcp_server.py --debug

Docker 部署

你也可以使用 Docker 运行服务：

# Build the Docker image
docker build -t zillow-mcp-server .

# Run with environment variables
docker run -p 8000:8000 -e ZILLOW_API_KEY=your_key_here zillow-mcp-server

# Or using an env file
docker run -p 8000:8000 --env-file .env zillow-mcp-server

与 Claude Desktop 搭配使用

将 Zillow MCP 服务添加到 Claude Desktop 配置文件中：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "zillow": {
      "command": "python",
      "args": ["/path/to/zillow_mcp_server.py"]
    }
  }
}

对于远程 HTTP 服务：

{
  "mcpServers": {
    "zillow-remote": {
      "command": "npx",
      "args": ["mcp-remote", "https://your-mcp-server-url.com/sse"]
    }
  }
}

可用工具

搜索房产

根据各种条件搜索房产：

search_properties(
    location: str,
    type: str = "forSale",
    min_price: Optional[int] = None,
    max_price: Optional[int] = None,
    beds_min: Optional[int] = None,
    beds_max: Optional[int] = None,
    baths_min: Optional[float] = None,
    baths_max: Optional[float] = None,
    home_types: Optional[List[str]] = None
)

在 Claude 中的用法示例：

Please search for properties in Seattle with prices between $500,000 and $800,000.

获取房产详情

获取特定房产的详细信息：

get_property_details(
    property_id: str = None,
    address: str = None
)

在 Claude 中的用法示例：

Can you get the details for the property with ID 12345?

获取 Zestimate 估值

获取 Zillow 对房产的估值：

get_zestimate(
    property_id: str = None,
    address: str = None
)

在 Claude 中的用法示例：

What's the Zestimate for 123 Main St, Seattle, WA?

获取市场趋势

获取特定地点的房地产市场趋势：

get_market_trends(
    location: str,
    metrics: List[str] = ["median_list_price", "median_sale_price", "median_days_on_market"],
    time_period: str = "1year"
)

在 Claude 中的用法示例：

What are the current real estate trends in Boston over the past year?

计算房贷

计算房贷还款额及相关费用：

calculate_mortgage(
    home_price: int,
    down_payment: int = None,
    down_payment_percent: float = None,
    loan_term: int = 30,
    interest_rate: float = 6.5,
    annual_property_tax: int = None,
    annual_homeowners_insurance: int = None,
    monthly_hoa: int = 0,
    include_pmi: bool = True
)

在 Claude 中的用法示例：

Calculate the monthly mortgage payment for a $600,000 house with 20% down and a 6% interest rate.

检查健康状态

验证 Zillow API 连接并获取服务状态：

check_health()

在 Claude 中的用法示例：

Please check if the Zillow API is currently responsive.

获取服务工具

获取此服务上所有可用工具的列表：

get_server_tools()

在 Claude 中的用法示例：

What tools are available in the Zillow MCP server?

可用资源

房产资源

以格式化文本资源的形式获取房产信息：

zillow://property/{property_id}

市场趋势资源

以格式化文本资源的形式获取市场趋势信息：

zillow://market-trends/{location}

错误处理

服务实现了稳健的错误处理，包括：

• 指数退避自动重试
• 详细的错误日志记录
• 速率限制处理
• 连接超时
• 平稳降级

技术架构

此 MCP 服务使用以下技术构建：

• FastMCP：用于构建模型上下文协议服务的 Python 风格框架
• Requests：用于向 Zillow Bridge API 发送 HTTP 请求，并支持连接池和重试
• Backoff：用于实现指数退避重试逻辑
• python-dotenv：用于管理环境变量

该服务提供工具（交互式函数）和资源（静态数据），Claude 可访问这些内容，为用户提供房地产信息。

限制与注意事项

• Zillow API 有使用限制（通常每个数据集每天 1,000 次请求）
• Zillow 的服务条款禁止在本地存储数据；所有请求都必须动态发起
• 你必须在用户界面中正确注明数据来源为 Zillow
• Bridge API 格式可能会发生变化；如需了解更新，请参阅 Zillow 文档

贡献

欢迎贡献！请随时提交 Pull Request。

1. Fork 此仓库
2. 创建功能分支：git checkout -b feature-name
3. 提交更改：git commit -m 'Add some feature'
4. 推送到分支：git push origin feature-name
5. 提交拉取请求

许可证

此项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

致谢

• FastMCP：提供 Pythonic MCP 实现
• Zillow：提供房地产数据 API
• Model Context Protocol：提供标准协议规范