arv-mcp

An MCP server that estimates a home's after-repair value (ARV) from nearby sold comps, and hands the model the scored evidence behind the number so it can explain, check and challenge it.

Ask Claude "What's the ARV of 1234 Main St?" and it gets back a typical value, a renovated range, a confidence tier, the comps that support it (and the ones that were thrown out, with reasons), what's listed nearby right now, and warnings about anything that should make it cautious.

You:    What's the ARV of 1234 Main Street?

Claude: Typical value is about $516k ($263/sqft on 1,961 sqft), based on
        20 eligible sales, 5+ of them within a quarter mile (confidence 5/5).
        Renovated comps support $541k–$586k. The closest match, 1260 Main
        Street, sold 23 days ago for $465k ($272/sqft): same subdivision,
        a bit smaller, no pool.

        Worth knowing: this house itself sold this week for $432,500
        ($220/sqft), well under the comp-based value. That usually means it
        sold in rough condition, which fits a flip at the renovated range.
        Two of the eligible comps were distressed sales; without them the
        median barely moves.

Not an appraisal. Data comes from public listings on Realtor.com via HomeHarvest and can be wrong or missing. Use it for research and as a starting point, not for lending or legal decisions.

How it works

address ──► verify the property ──► sold comps ──► score & gate ──► estimate
               │  (any status)        within 1.5 mi    each comp       + evidence
               └─ not verified? ──► locate it + ask for its facts

1. Find the subject. The address is resolved to Realtor.com's record for exactly that street and unit, whether it's for sale, pending, sold or off market. Realtor.com's geocoder will happily return the wrong house for a bad address, so every result is checked against the street and unit typed. If nothing verifies, the address is located (Census geocoder, or caller-supplied lat/lon) and the tool asks for the facts it needs (sqft, property_type) instead of guessing.

2. Pull comps around the subject's coordinates: sold in the last 180 days within 1.5 miles (both adjustable per call), ±40% of the subject's size, same property type. The subject's own sale is pulled out and reported separately, so a just-sold house can't comp itself.

3. Score every comp on 13 factors: size, year built, lot, beds/baths, property type, recency, condition signals, distance, subdivision, garage, stories, pool and basement. Each known factor also has a floor. A comp that fails any one (a different property type, a much bigger house, one built decades apart) is excluded outright, however good it looks elsewhere. Size, age and lot floors loosen for comps right next door and tighten with distance.

4. Check the micro-market. Each comp's subdivision median (or its own $/sqft) must sit within ±20% of the subject's local price level, so a great physical match in a pricier pocket doesn't inflate the estimate. Subdivisions come from the MLS "Subdivision" field, with phases like "Unit 2" or "Ph 04 Sec 01" merged.

5. Estimate:

   • Typical value: similarity-weighted median $/sqft × subject sqft.
   • Renovated range: weighted 75th–90th percentile, what the top of the pool supports.
   • Confidence 1–5: how close the supporting comps are.

   If no comp survives, the tool falls back to the area's going rate and says plainly that the number isn't comp-backed.

Tools

get_arv

Returns subject, estimate (arv, renovated_range, arv_fallback, window), confidence, pool_stats, eligible_comps (each with the factors that cost it points and any distress flags), excluded_comps (with reasons), market_context and guidance. Unknown facts are null, never 0.

lookup_property

The verified record for an address: size, beds/baths, year, lot, stories, garage, pool, subdivision, status, list price (only while it's on the market) and last sale.

Prompt: analyze_arv

An appraiser-style walkthrough (subject → comps → adjustments → range). Shows up as a slash command in Claude Code.

Errors

Failures come back as {"error": {"code", "message", ...}} so the model can act on them:

Install

Requires Python 3.11+. Published on PyPI and listed in the MCP Registry as io.github.mariov7757/arv-mcp.

Claude Code

claude mcp add arv-mcp -- uvx arv-mcp

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "arv-mcp": {
      "command": "uvx",
      "args": ["arv-mcp"]
    }
  }
}

pip

pip install arv-mcp

To run the unreleased main branch instead, use uvx --from git+https://github.com/mariov7757/arv-mcp arv-mcp.

From a clone

git clone https://github.com/mariov7757/arv-mcp && cd arv-mcp
python -m venv .venv && .venv/bin/pip install -e ".[dev]"
claude mcp add arv-mcp -- "$PWD/.venv/bin/arv-mcp"

Windows: if uvx fails installing pywin32 (os error 32 / "being used by another process", usually antivirus scanning uv's temporary build folder), install into a regular virtualenv instead and point the client at the installed executable:

uv venv $HOME\.arv-mcp
uv pip install --python $HOME\.arv-mcp\Scripts\python.exe arv-mcp
claude mcp add arv-mcp -- $HOME\.arv-mcp\Scripts\arv-mcp.exe

Configuration

All optional, via environment variables:

A full get_arv makes 5 requests to Realtor.com (2 to look up the subject, 1 for sold comps, 2 for active/pending) and takes ~4–6 s. Results are cached for 15 minutes, so follow-ups and what-ifs on the same address return instantly.

Limitations

• Tuned on Phoenix metro. Gate bands and confidence tiers were calibrated on ~8,000 Phoenix-area valuations. The engine runs anywhere in the US, but in other markets (especially rural or low-volume ones) lean on the comps and confidence tier, and widen radius_mi / days_back.
• Typical value isn't condition-aware. Distressed sales are flagged (MLS REO/short-sale conditions, "fixer"/"as-is" language) and their effect on the median is reported, but they aren't excluded.
• $/sqft is the wrong tool for some properties. Land is refused; farms, multi-family and mobile homes get a warning.
• Unofficial data source. HomeHarvest scrapes Realtor.com's public site. Requests run from your own machine and are rate-limited, but the site can change or block access at any time. homeharvest is pinned to a tested range because the client relies on its internals.

Development

pip install -e ".[dev]"
pytest            # offline suite; real network calls are blocked
ARV_MCP_LIVE_ADDRESS="<a real address>" pytest -m live   # smoke tests against Realtor.com + Census
ruff check src tests

src/arv_mcp/
  server.py         MCP tools, instructions and prompt
  service.py        address in, estimate + evidence out
  arv.py            eligibility, weighted median, renovated range, confidence
  scoring.py        per-comp gated scoring
  comps.py          comp normalization and bad-data filters
  ratelimit.py      token buckets
  data/client.py    Realtor.com transport over HomeHarvest
  data/homeharvest.py  subject lookup, comp searches, field extraction
  data/geocode.py   Census geocoder

Releasing

The version lives in one place: __version__ in src/arv_mcp/__init__.py.

1. Bump __version__ (patch for fixes, minor for new tools, parameters or fields) and merge to main with CI green.

2. Tag the release and push the tag:

   git tag v0.2.0
   git push origin v0.2.0
   

The Release workflow then:

• checks that the tag matches __version__
• runs lint and tests, and builds the package
• publishes to PyPI with Trusted Publishing (no API token)
• stamps the version into server.json and publishes it to the MCP Registry as io.github.mariov7757/arv-mcp, authenticated by GitHub OIDC

PyPI versions are permanent. A broken release gets yanked on PyPI and replaced by the next patch version; a version number is never reused.

License

MIT