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:

# 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:

# 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

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

For remote HTTP server:

{
  "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:

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:

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:

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:

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:

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:

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:

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