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

Tools (10)

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.