RE Data Refinery MCP Server

A Model Context Protocol (MCP) server that turns messy real estate data into clean, scored, AI-ready property intelligence for Columbus, OH and surrounding metro cities.

Unlike generic property APIs, the RE Data Refinery combines live Zillow data with county-level enrichment (GIS, tax delinquency, sheriff sales, permits, probate records) and computes proprietary investment scores for every listing. Agents pay only for the queries they run — no subscriptions, no API tiers — via the x402 micropayment protocol on Base mainnet.

• Live data source: ZillAPI
• Coverage: 150+ properties seeded across 14 Columbus metro cities
• Payment: USDC on Base, $0.35 per paid lookup
• Transport: stdio / SSE for Claude Desktop, Claude Code, ChatGPT Desktop, Hermes, and other MCP clients

---

What makes it different

Feature	RE Data Refinery	BatchData / USDV Capital
Pricing	Pay per query via x402 (no subscription)	Free tiers or monthly subscriptions
Scoring	Flip, wholesale, rental yield, market heat	Usually absent or generic
Enrichment	County GIS, tax delinquency, sheriff sales, permits, probate	Typically surface-level listing data
On-chain settlement	USDC on Base via Permit2 + CDP facilitator	Not applicable

---

Tools (10)

Tool	Description	Price
refinery_health	API health, cached property count, rate limit status	Free
refinery_credits	Upstream ZillAPI credit balance	Free
refinery_properties	List scored properties by city with optional price filters	$0.35 (live), free (cached)
refinery_property_detail	Full scored detail for a single property by ZPID	$0.35
refinery_property_price_history	Price/transaction timeline for a property	$0.25
refinery_property_tax_history	Tax and assessment history for a property	$0.25
refinery_property_schools	School ratings near a property	$0.25
refinery_search	Natural-language property search	$0.50
refinery_scored_search	Search filtered/scored by investment criteria	$0.50
refinery_payment_status	Show x402 configuration and active API base URL	Free

---

Quick start

1. Install dependencies

pip install "x402>=2.20.0" eth-account httpx

2. Clone the repository

git clone https://github.com/areshms/re-refinery-mcp.git
cd re-refinery-mcp

3. Configure your environment

Create a .env file in the project root:

# Required for paid Worker lookups
EVM_PRIVATE_KEY=0x...

# Optional
X402_SPEND_CAP=$1                    # max per-payment USD cap (default: $1)
REFINERY_BASE_URL=https://re-data-refinery.ares-hms.workers.dev
REFINERY_LOCAL_URL=http://localhost:5004

Your wallet must hold USDC on Base to pay for lookups.

4. Add to your MCP client

Claude Desktop / Claude Code:

{
  "mcpServers": {
    "re_refinery_mcp": {
      "command": "python3",
      "args": ["/path/to/re-refinery-mcp/re_refinery_mcp.py"],
      "env": {
        "EVM_PRIVATE_KEY": "${EVM_PRIVATE_KEY}",
        "X402_SPEND_CAP": "$1"
      }
    }
  }
}

---

Local development mode

To develop or test without spending USDC, disable x402 and point at a free local API:

export REFINERY_ENABLE_X402=false
export REFINERY_LOCAL_URL=http://localhost:5004
python3 re_refinery_mcp.py --transport stdio

Paid endpoints then call localhost:5004 instead of the Worker.

---

How payments work

1. Your agent requests a paid endpoint.
2. The Worker responds with HTTP 402 Payment Required and an x402 payment requirement.
3. The MCP client signs a Permit2 USDC transaction on Base.
4. The CDP facilitator verifies the signature and settles the payment on-chain.
5. The Worker returns the requested data.

All of this is handled automatically once EVM_PRIVATE_KEY is configured.

---

Scoring methodology

Every property is enriched with:

• flip_score (0–100): discount vs. Zestimate, days on market, neighborhood median, age, lot size
• wholesale_score (0–100): equity spread, tax delinquency, DOM, owner-occupancy, price vs. Zestimate
• rental_yield_pct: annual rent estimate ÷ price
• market_heat: Hot / Warm / Cool based on days on market and recent price trend

Scores are recomputed against neighborhood medians drawn from the live-refinery cache.

---

Requirements

• Python 3.11+
• x402>=2.20.0
• eth-account
• httpx
• A wallet with USDC on Base mainnet

---

Worker

The Cloudflare Worker backing this server is deployed at:

https://re-data-refinery.ares-hms.workers.dev

It is the first real estate data refinery using Cloudflare's x402 monetization gateway.

---

License

MIT

---

Built by Hightower Marketing — making real estate data work for AI agents.