Content
# README.md - Zillow MCP Server
A Model Context Protocol (MCP) server that provides real-time access to Zillow real estate data, built with Python and FastMCP.
## Features
* 🏠 **Property Search**: Search for properties by location, price range, and property features
* 💰 **Property Details**: Get detailed information about specific properties
* 📊 **Zestimates**: Access Zillow's proprietary home valuation data
* 📈 **Market Trends**: View real estate market trends for any location
* 🧮 **Mortgage Calculator**: Calculate mortgage payments based on various inputs
* 🔍 **Health Check**: Verify API connectivity and monitor performance
## Requirements
* Python 3.8 or higher
* A Zillow Bridge API key (request access at api@bridgeinteractive.com)
## Installation
1. Clone this repository:
```
git clone https://github.com/rohitsingh-iitd/zillow-mcp-server
cd zillow-mcp-server
```
2. Install the dependencies:
```
pip install -r requirements.txt
```
3. Create a `.env` file with your Zillow API key:
```
ZILLOW_API_KEY=your_zillow_api_key_here
```
## Usage
Run the server with options:
```bash
# 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
```
You can also run the server using Docker:
```bash
# 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
```
## Usage with Claude Desktop
Add the Zillow MCP server to your Claude Desktop configuration file:
* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"zillow": {
"command": "python",
"args": ["/path/to/zillow_mcp_server.py"]
}
}
}
```
For remote HTTP server:
```json
{
"mcpServers": {
"zillow-remote": {
"command": "npx",
"args": ["mcp-remote", "https://your-mcp-server-url.com/sse"]
}
}
}
```
## Available Tools
### search_properties
Search for properties based on various criteria:
```python
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
)
```
Example usage in Claude:
```
Please search for properties in Seattle with prices between $500,000 and $800,000.
```
### get_property_details
Get detailed information about a specific property:
```python
get_property_details(
property_id: str = None,
address: str = None
)
```
Example usage in Claude:
```
Can you get the details for the property with ID 12345?
```
### get_zestimate
Get Zillow's estimated value for a property:
```python
get_zestimate(
property_id: str = None,
address: str = None
)
```
Example usage in Claude:
```
What's the Zestimate for 123 Main St, Seattle, WA?
```
### get_market_trends
Get real estate market trends for a specific location:
```python
get_market_trends(
location: str,
metrics: List[str] = ["median_list_price", "median_sale_price", "median_days_on_market"],
time_period: str = "1year"
)
```
Example usage in Claude:
```
What are the current real estate trends in Boston over the past year?
```
### calculate_mortgage
Calculate mortgage payments and related costs:
```python
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
)
```
Example usage in Claude:
```
Calculate the monthly mortgage payment for a $600,000 house with 20% down and a 6% interest rate.
```
### check_health
Verify the Zillow API connection and get server status:
```python
check_health()
```
Example usage in Claude:
```
Please check if the Zillow API is currently responsive.
```
### get_server_tools
Get a list of all available tools on this server:
```python
get_server_tools()
```
Example usage in Claude:
```
What tools are available in the Zillow MCP server?
```
## Resources
Get property information as a formatted text resource:
```
zillow://property/{property_id}
```
Get market trends information as a formatted text resource:
```
zillow://market-trends/{location}
```
## Error Handling
The server implements robust error handling with:
* Automatic retries with exponential backoff
* Detailed error logging
* Rate limit handling
* Connection timeouts
* Graceful degradation
## Technical Details
This MCP server is built using:
* **FastMCP**: A Pythonic framework for building Model Context Protocol servers
* **Requests**: For making HTTP requests to the Zillow Bridge API with connection pooling and retries
* **Backoff**: For implementing exponential backoff retry logic
* **python-dotenv**: For managing environment variables
The server provides both tools (interactive functions) and resources (static data) that Claude can access to provide real estate information to users.
## Limitations and Considerations
* Zillow's API has usage limits (typically 1,000 requests per day per dataset)
* Zillow's terms of service prohibit storing data locally; all requests must be dynamic
* You must properly attribute data to Zillow in the user interface
* The Bridge API functionality may change over time, requiring server updates
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Acknowledgments
* Zillow for providing the Bridge API
* Anthropic for the Model Context Protocol specification
