芝麻房屋-MCP服务器

Name: 芝麻房屋-MCP服务器
Author: sap156

作者：sap15620 星标更新：2025-05-09

安装使用来源：spider==github.com

项目介绍

Zillow MCP Server

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

特性

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

安装

先决条件

Python 3.8或更高版本
Zillow Bridge API密钥（在api@bridgeinteractive.com请求访问）

设置

克隆此仓库：

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

安装依赖项：
```
pip install -r requirements.txt
```
创建一个包含您的Zillow API密钥的.env文件：
```
ZILLOW_API_KEY=your_zillow_api_key_here
```

运行服务器

使用选项运行服务器：

# 标准标准输入输出模式（适用于Claude Desktop）
python zillow_mcp_server.py

# HTTP服务器模式（用于远程访问）
python zillow_mcp_server.py --http --port 8000

# 调试模式以获得更详细的日志
python zillow_mcp_server.py --debug

Docker部署

您也可以使用Docker运行服务器：

# 构建Docker镜像
docker build -t zillow-mcp-server .

# 使用环境变量运行
docker run -p 8000:8000 -e ZILLOW_API_KEY=your_key_here zillow-mcp-server

# 或者使用.env文件
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中的示例用法：

请搜索西雅图价格在500,000美元至800,000美元之间的房产。

获取房产详情

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

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

在Claude中的示例用法：

你能获取ID为12345的房产详情吗？

获取Zestimate

获取Zillow对房产的估价：

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

在Claude中的示例用法：

123 Main St, Seattle, WA的Zestimate是多少？

获取市场趋势

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

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

在Claude中的示例用法：

波士顿过去一年的房地产趋势是什么？

计算抵押贷款

计算抵押贷款支付及相关费用：

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中的示例用法：

计算价值600,000美元的房子，首付20%，利率6%的月度抵押贷款支付。

检查健康状况

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

check_health()

在Claude中的示例用法：

请检查Zillow API当前是否响应。

获取服务器工具

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

get_server_tools()

在Claude中的示例用法：

Zillow MCP服务器有哪些可用工具？

可用资源

房产资源

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

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的文档以获取更新

贡献

欢迎贡献！请随意提交拉取请求。

分叉仓库
创建功能分支：git checkout -b feature-name
提交您的更改：git commit -m 'Add some feature'
推送到分支：git push origin feature-name
提交拉取请求

许可证

本项目采用MIT许可证——请参阅LICENSE文件了解详细信息。

致谢

FastMCP 用于Python的MCP实现
Zillow 提供房地产数据API
Model Context Protocol 用于标准协议规范