Zillow MCP Server

# 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