Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/sap156/zillow-mcp-server

Zillow MCP Server for real estate data access via the Model Context Protocol
https://github.com/sap156/zillow-mcp-server

Last synced: 3 months ago
JSON representation

Zillow MCP Server for real estate data access via the Model Context Protocol

Awesome Lists containing this project

README 

          
# 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



## Installation



### Prerequisites



- Python 3.8 or higher

- A Zillow Bridge API key (request access at api@bridgeinteractive.com)



### Setup



1. Clone this repository:

   ```

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

   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

   ```



### Running the Server



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

```



### Docker Deployment



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?

```



## Available Resources



### Property Resource



Get property information as a formatted text resource:



```

zillow://property/{property_id}

```



### Market Trends Resource



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 Architecture



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 format may change; refer to Zillow's documentation for updates



## 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](https://github.com/jlowin/fastmcp) for the Pythonic MCP implementation

- [Zillow](https://www.zillow.com) for providing real estate data APIs

- [Model Context Protocol](https://modelcontextprotocol.io) for the standard protocol specification