# 🏡 Open-Source Property Intelligence MCP Server

A 100% Free and Open-Source Model Context Protocol (MCP) Server for property and parcel intelligence. Powered exclusively by official public US government data APIs (**USGS 3DEP Elevation**, **FEMA NFHL Flood Hazard REST API**, **USDA NRCS Soil Data Access API**, **EPA Facility Registry Service**, **USFS Active & Historical Wildfire APIs**, **USGS Earthquake Hazards API**, **US Census Bureau ACS API**), open government land auctions, open county assessor GIS REST APIs, official County Recorder legal public records, FSBO portals, direct Redfin Stingray GIS APIs, and active API catalogue health diagnostics.

> **CRITICAL GUARANTEE**: Zero paid APIs, commercial scrapers (Zillow, RentCast, RapidAPI), or subscription keys required. 100% free forever.

---

## 🛠️ Features & Tools Supported

The server exposes **16 primary tools** adhering strictly to MCP standards:

| Tool Name | Parameters | Description |
| :--- | :--- | :--- |
| `calculate_land_affordability` | `total_budget: float`, `estimated_site_prep: float` | Calculates the maximum safe land purchase price based on budget and required site preparation (well, septic, driveway, power). |
| `get_fema_hazard_zone` | `lat: float`, `lon: float` | Queries official free FEMA Flood Hazard MapServer REST API for flood zone codes, Special Flood Hazard Area (SFHA) flags, and risk levels. |
| `verify_tsunami_elevation` | `lat: float`, `lon: float` | Queries free USGS 3DEP Elevation API to verify if parcel elevation meets or exceeds the **100-foot tsunami safety threshold**. |
| `get_usda_soil_survey` | `lat: float`, `lon: float` | Queries official free **USDA NRCS Soil Data Access API** for soil composition, drainage class, hydric/wetland rating, and septic tank absorption field suitability. |
| `check_epa_environmental_hazards` | `lat: float`, `lon: float`, `radius_miles: float = 5.0` | Queries official free **EPA Facility Registry Service API** for nearby Superfund, Toxic Release Inventory (TRI), or hazardous industrial facilities. |
| `get_wildfire_hazard_risk` | `lat: float`, `lon: float`, `radius_miles: float = 15.0` | Queries official free **USFS/NIFC WFIGS Wildfire REST APIs** for active wildfire incidents AND **historical wildfire perimeters, past burned acreage, and long-term hazard risk levels**. |
| `get_usgs_seismic_hazard` | `lat: float`, `lon: float`, `radius_km: float = 50.0`, `min_magnitude: float = 2.5` | Queries official free **USGS Earthquake Hazards FDSN API** for historical and recent earthquake activity and seismic risk levels. |
| `analyze_county_assessor_data` | `file_path: str`, `max_price: float`, `min_acres: float`, `require_direct_road_access: bool`, `require_public_utilities: bool` | Parses local open county assessor CSV datasets to filter parcels by price, acreage, direct road frontage (excluding landlocked parcels), and public utilities. |
| `rank_parcels_by_suitability` | `file_path: str`, `max_price: float`, `min_acres: float`, `require_direct_road_access: bool`, `require_public_utilities: bool`, `budget_weight: float`, `size_weight: float`, `road_weight: float`, `utility_weight: float` | Multi-criteria parcel ranking engine that scores parcels **0 to 100** based on price/acre, budget compliance, acreage size, road frontage, and utilities. |
| `fetch_live_land_listings` | `state: str = 'CA'`, `min_acres: float`, `max_price: float`, `query: str`, `limit: int = 10` | Fetches live active land and real estate listings from open public databases and government surplus property auctions with verified direct listing URLs. |
| `fetch_county_parcels_online` | `state: str = 'CA'`, `county: str`, `max_price: float`, `min_acres: float`, `require_direct_road_access: bool`, `require_public_utilities: bool`, `limit: int = 10` | Automatically fetches county tax assessor parcel records online from open government GIS APIs without requiring manual CSV uploads. |
| `search_redfin_gis_listings` | `location: str = 'Brookings, OR'`, `property_type: str = 'land'`, `min_acres: float`, `max_price: float`, `limit: int = 10` | Direct HTTP query engine to Redfin Stingray GIS API endpoint. Fetches live active MLS listings in **0.3 seconds** with zero browser automation required! |
| `fetch_county_pre_foreclosures` | `state: str = 'CA'`, `county: str`, `max_default_amount: float`, `min_acres: float`, `limit: int = 10` | Queries official County Recorder / Register of Deeds public records for Notice of Default (NOD) and Notice of Trustee Sale (NTS) legal filings directly without going through Zillow. |
| `fetch_fsbo_portal_listings` | `state: str = 'OR'`, `county: str`, `min_acres: float`, `max_price: float`, `limit: int = 10` | Fetches unrepresented private seller FSBO land & property listings directly from **FSBO.com**, **ForSaleByOwner.com**, and **Craigslist Real Estate By Owner**. |
| `check_api_health_status` | *None* | Probes all 11 external US Government APIs, auction portals, county GIS clearinghouses, and MLS endpoints live. Reports operational status, HTTP response codes, and round-trip latency in milliseconds. |
| `fetch_historical_comps` | `address: str`, `lat: float`, `lon: float`, `radius_miles: float = 3.0`, `min_acres: float`, `max_acres: float`, `months_back: int = 24`, `property_type: str = 'land'`, `limit: int = 10` | Retrieves historical real estate & land sold comparable (comp) data using tiered open GIS APIs, public Redfin sold feeds (`include_sold=true`), and US Census Bureau ACS data. Returns summary metrics & price/acre. |

---

## 🚀 Setup & Installation

### Prerequisites
- Python 3.10 or higher installed.

### 1. Set Up Virtual Environment

```bash
cd /path/to/property_mcp

# Create a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt
```

---

## 🧪 Running Tests

Verify all 20 tools using `pytest`:

```bash
.venv/bin/python -m pytest tests/
```

---

## 💻 Registering with MCP Host (e.g. Antigravity Desktop / Claude Desktop)

Add the following configuration block to your configuration file:

```json
{
  "mcpServers": {
    "property-intelligence": {
      "command": "/path/to/property_mcp/.venv/bin/python",
      "args": [
        "/path/to/property_mcp/server.py"
      ],
      "env": {}
    }
  }
}
```

---

## 📊 Sample Usage

### 1. Retrieve Historical Sold Comps (Davenport, CA - 24 Months Lookback)
```json
{
  "name": "fetch_historical_comps",
  "arguments": {
    "address": "Davenport, CA",
    "radius_miles": 5.0,
    "months_back": 24,
    "property_type": "land",
    "limit": 5
  }
}
```

### 2. Run Live API Health & Latency Diagnostic Dashboard
```json
{
  "name": "check_api_health_status",
  "arguments": {}
}
```