Metadata-Version: 2.4
Name: iflow-mcp_rohitsingh-iitd-zillow-mcp-server
Version: 0.1.0
Summary: A Model Context Protocol (MCP) server that provides real-time access to Zillow real estate data
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp>=0.5.0
Requires-Dist: requests>=2.28.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: backoff>=2.2.1
Requires-Dist: pydantic>=2.0.0
Requires-Dist: uvicorn>=0.22.0
Requires-Dist: fastapi>=0.95.0
Dynamic: license-file

# 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
