Zillow MCP Server

A Model Context Protocol (MCP) server that provides real-time access to Zillow real estate data via dual backends — Bright Data Web Scraper API and Zillow Bridge API — built with Python and FastMCP.

Features

• 🏠 Property Search: Search for properties by location, price range, and property features using Bright Data
• 💰 Property Details: Get detailed information about specific properties using Bright Data
• 📊 Zestimates: Access Zillow's proprietary home valuation data using Bright Data
• 📈 Market Trends: View real estate market trends for any location using Bright Data
• 🧮 Mortgage Calculator: Calculate mortgage payments based on various inputs (always-on)
• 🔍 Health Check: Verify API connectivity and monitor performance across backends (always-on)
• 🏢 MLS Listings: Access exclusive MLS-only listings via Zillow Bridge API (requires key and manual setup)
• 📦 Server Tools: Get a list of all available tools on this server (always-on)

Architecture Overview

The Zillow MCP Server uses a dual-backend architecture to provide access to both public and MLS-only real estate data:

zillow_mcp_server.py       # FastMCP entrypoint, env detection, conditional registration
backends/
  base.py                  # build_envelope, make_session, BackendError, BaseClient
  bridge.py                # BridgeClient (MLS-only, currently stub-wired)
  brightdata.py            # BrightDataClient (sync + async polling)
  urls.py                  # Zillow URL builders
tools/
  public.py                # search/details/zestimate/market_trends → Bright Data
  mls.py                   # get_mls_listing (stub until Bridge access)
  mortgage.py              # calculate_mortgage (pure math)
  health.py                # check_health (multi-backend)
  introspect.py            # get_server_tools (dynamic from mcp.list_tools())
  resources.py             # zillow:// resource markdown formatters

Installation

Prerequisites

• Python 3.8 or higher
• pip
• Docker (optional for deployment)

Setup Steps

1. Clone the repository:

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

2. Install dependencies:

   pip install -r requirements.txt

Running the Server

To start the server:

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

To run the server in a Docker container:

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

# Run with environment variables
docker run -p 8000:8000 \
  -e BRIGHTDATA_API_TOKEN=your_brightdata_token \
  -e BRIGHTDATA_ZILLOW_PROPERTIES_DATASET_ID=your_dataset_id \
  -e BRIGHTDATA_ZILLOW_SEARCH_DATASET_ID=your_search_dataset_id \
  -e BRIGHTDATA_ZILLOW_MARKET_DATASET_ID=your_market_dataset_id \
  -e ZILLOW_API_KEY=your_bridge_api_key \
  zillow-mcp-server

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

Configuration

Environment Variables

Env var	Required for	Notes
BRIGHTDATA_API_TOKEN	All public tools	Sign up at brightdata.com (free 5K req/mo tier)
BRIGHTDATA_ZILLOW_PROPERTIES_DATASET_ID	get_property_details, get_zestimate, zillow://property resource	Find in your Bright Data dashboard under Web Scraper datasets
BRIGHTDATA_ZILLOW_SEARCH_DATASET_ID	search_properties	Same
BRIGHTDATA_ZILLOW_MARKET_DATASET_ID	get_market_trends, zillow://market-trends resource	Same
ZILLOW_API_KEY	get_mls_listing (currently stubbed)	Bridge API key from api@bridgeinteractive.com (gated to MLS members). The placeholder replace_me_with_real_bridge_api_key is rejected.

Tool Registration

Tools are conditionally registered based on environment variables:

• Always-on tools: calculate_mortgage, check_health, get_mls_listing, get_server_tools
• Bright Data tools: search_properties, get_property_details, get_zestimate, get_market_trends

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

Calculate Mortgage

Backend: Always-on

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

Backend: Always-on

check_health()

Example usage in Claude:

Please check if the Zillow API is currently responsive.

Get MLS Listing

Backend: Bridge API (stub until configured)

get_mls_listing(zpid: str = None, address: str = None)

Example usage in Claude:

Get the MLS listing for 123 Main St, Seattle, WA.

Get Server Tools

Backend: Always-on

get_server_tools()

Example usage in Claude:

What tools are available in the Zillow MCP server?

Search Properties

Backend: Bright Data

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

Backend: Bright Data

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

Backend: Bright Data

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

Backend: Bright Data

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?

Available Resources

• zillow://property/{property_id} — Property details (requires Bright Data)
• zillow://market-trends/{location} — Market trends (requires Bright Data)

MLS-only Access (Advanced)

To enable MLS-only access, you must:

1. Provide a real ZILLOW_API_KEY in your environment
2. Manually replace the stub in tools/mls.py with a call to BridgeClient.get_mls_listing (the TODO comment marks the replacement point)

The key alone does not enable the feature — the stub must be replaced manually.

Error Handling

The server implements robust error handling with:

• Automatic retries with exponential backoff (split between Bright Data and Bridge backends)
• Detailed error logging
• Rate limit handling
• Connection timeouts
• Graceful degradation

Bright Data backend uses make_session with backoff_factor=1.0, while Bridge backend uses @backoff.on_exception.

Technical Architecture

This MCP server is built using:

• FastMCP: A Pythonic framework for building Model Context Protocol servers
• Requests: For making HTTP requests to both Bright Data and Zillow Bridge APIs
• Backoff: For implementing exponential backoff retry logic
• python-dotenv: For managing environment variables
• Responses: For mocking HTTP responses in tests
• Pytest: For running tests
• Pytest-mock: For mocking in tests
• Pytest-asyncio: For async testing

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 format may change; refer to Zillow's documentation for updates
• Bright Data has rate limits and may require additional configuration for high-volume usage
• Bright Data dataset IDs are user-provided and may need updating if Bright Data changes their dataset structure.
• Bright Data response shapes are normalized by tools/public.py:_normalize_property — the first real call may surface field-name mismatches that need a follow-up to that mapping (a TODO comment marks the spot).

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Commit your changes: git commit -m 'Add some feature'
4. Push to the branch: git push origin feature-name
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• FastMCP for the Pythonic MCP implementation
• Zillow for providing real estate data APIs
• Model Context Protocol for the standard protocol specification
• Bright Data for web scraping APIs