convez.ai
MCP ServerIntegração & APIsIntermediário
jsconiers

Cornerstone: Inteligência Imobiliária com MCP

jsconiers/cornerstone-mcp

156 ferramentas de análise imobiliária integradas ao Claude via MCP

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP especializado em real estate com 156 ferramentas para busca de imóveis, avaliação, análise de mercado, inteligência financeira e diligência. Integra dados de múltiplas fontes (RentCast, ATTOM, FRED, Census, Walk Score) com suporte a filtros por tempo de deslocamento e geração de mapas. Arquitetura modular com provedores plugáveis (mock, rentcast, rapidapi, apify) para funcionar offline ou com APIs reais.

Instalação

$npx convez-ai jsconiers/cornerstone-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 5 meses
Versão
v0.2.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Análise de propriedades e avaliação comparativa (CMA) para agentes/corretores
  • Inteligência de investimento (ROI, fix-and-flip, rentabilidade) para investidores
  • Busca avançada com filtros por vizinhança, comutação e dados de mercado
  • Enriquecimento de dados imobiliários com histórico de vendas e previsões

Veredito

Cornerstone é uma solução robusta e bem-arquitetada para automação de análise imobiliária. Recomendado para profissionais do setor que precisam integrar múltiplas fontes de dados. Pontos fortes: cobertura abrangente, flexibilidade de provedores e documentação clara. Consideração: requer credenciais de APIs externas para funcionamento completo (mock data permite prototipagem).

README

A tradução para o português deste README ainda está na fila.

Cornerstone

The cornerstone of every real-estate decision.

License: MIT Python Tools Protocol: MCP PRs welcome

Cornerstone is a local Model Context Protocol (MCP) server for US real-estate work: search listings and rentals, pull valuations and comparables, read market and neighborhood stats, save searches, and — uniquely — filter by commute and generate map links. It runs over STDIO and ships with a pluggable data layer so the same tools work against mock data, a licensed API, or community scraper backends.

This is a clean-room reference architecture inspired by the (demo-only) agentic-ops/real-estate-mcp repo: it keeps that project's modular shape and analysis-prompt themes but modernizes the transport (STDIO, not deprecated SSE), replaces the fictional dataset with a real provider abstraction, and adds mapping/commute tooling.

What you get

  • 83 tools across property search, valuation, rentals, market & neighborhood intelligence, geospatial/mapping, buyer finance, listing analytics, place/data lookups, monitoring, and persona toolkits for landlords, investors, developers, and agents/brokers.
  • MCP protocol features: argument completions, sampling, elicitation, progress + logging, and typed structured output (all degrade gracefully).
  • 10 resources (5 static + 5 dynamic templates) under realestate://.
  • 11 prompts — reusable workflows (property analysis, CMA, market report, investment ROI, fix-and-flip, buyer consultation, commute tradeoff, …).
  • Pluggable providers: mock (default, offline), rentcast, rapidapi, apify.
  • Full pytest suite (165 tests: unit + integration), all offline.

Quickstart

python -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt
python main.py            # starts the STDIO server (uses mock data out of the box)

Wire it into Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "cornerstone": {
      "command": "/abs/path/.venv/bin/python",
      "args": ["/abs/path/cornerstone-mcp/main.py"],
      "env": { "REALESTATE_PROVIDER": "mock" }
    }
  }
}

Choosing a data provider

The server boots with mock (deterministic metro-Atlanta sample data) so every tool works with no keys. Point it at real data with environment variables (see .env.example). If a real provider is selected but its credentials are missing, the server logs a warning to stderr and falls back to mock — call the provider_info tool to see what's actually active.

ProviderDataStabilityNotes
mockSamplen/aOffline; powers tests and demos.
rentcastListings, AVM value/rent, market statsHighLicensed API with a free tier. Recommended. Verify endpoint/field names against the current RentCast docs.
attomProperty records, AVM value, tax history, ownership, sale history, pre-foreclosureHighLicensed data API (no listings/search). Enrichment backend in hybrid mode, or standalone for records.
rapidapiZillow/Realtor wrappersMediumUnofficial; schema varies by publisher — set host/key/paths to match yours.
apifyZillow + Redfin + Realtor.com aggregatedLowerCommunity scraper actors behind one interface; set APIFY_ACTOR to e.g. nexgendata/real-estate-mcp-server (listings/comps/rentals/valuations, free tier), sovereigntaylor/real-estate-aggregator, or jonn/us-realestate-multisource. Powerful but break when sites change.
# Example: run against RentCast
export REALESTATE_PROVIDER=rentcast
export RENTCAST_API_KEY=sk_...
python main.py

Data / enrichment backend (hybrid, recommended)

REALESTATE_PROVIDER selects the listings/search backend; REALESTATE_DATA_PROVIDER selects the record/enrichment backend used by the valuation, tax-history, ownership, price-history, and details tools. With an ATTOM_API_KEY set, the default is a hybrid: RentCast serves listings/search while ATTOM serves property records and AVMs, with automatic fall-back to the listings provider when ATTOM has no record on file.

REALESTATE_DATA_PROVIDERListings/searchRecords (value/tax/owner/history)
auto (default)RentCastATTOM if ATTOM_API_KEY set, else RentCast
rentcastRentCastRentCast
attomRentCastATTOM

For ATTOM standalone (records only, no search) set REALESTATE_PROVIDER=attom. The blended_valuation tool queries both backends and returns a confidence-weighted blend.

# Hybrid: RentCast listings + ATTOM records (the sensible default)
export REALESTATE_PROVIDER=rentcast
export RENTCAST_API_KEY=...
export ATTOM_API_KEY=...
export REALESTATE_DATA_PROVIDER=auto
python main.py

Legal note: the rapidapi and apify backends rely on unofficial access to Zillow/Redfin/Realtor.com and sit in a Terms-of-Service gray area; they can also break without warning. For production use prefer a licensed feed (RentCast). The adapters are included as working templates — verify each provider's endpoints and terms before relying on them.

Mapping & commute

  • geocode_address, area_boundary_box — coordinates and bounding boxes.
  • filter_by_commute — pull listings near a location and keep only those within an N-minute one-way budget of an anchor (e.g. "Cumberland, GA"). Uses a straight-line drive-time proxy at a configurable average speed; set REALESTATE_GEOCODER=google + a key for real geocoding (and extend with Distance Matrix for true drive times).
  • map_links_for_property, directions_to_property — Google Maps / OSM links (and a Google Static Maps image URL when GOOGLE_MAPS_API_KEY is set).

Architecture

main.py            build_server() wires everything; STDIO entry point
config.py          env-driven Config + load_config()
models.py          Listing, Valuation, MarketStats, Area, Comp (+ to_dict)
geo.py             pure geo math, map-link builders, Geocoder
utils.py           formatting, TTL cache, pagination, error mapping
context.py         ServerContext (deps passed to tool groups)
store.py           SavedSearchStore (in-memory + optional JSON persistence)
providers/         base ABC + mock, rentcast, attom, rapidapi, apify + factory
tools/             31 modules registering 156 tools
resources/         10 resources (static + templates)
prompts/           11 workflow prompts
tests/             unit/ + integration/

Tools are thin: they validate inputs (Pydantic Annotated params → flat JSON schemas), call a provider method, and format the result. All business logic lives in providers + geo/utils, so it's unit-testable independent of MCP.

Tools (156)

  • Property (7): search_properties, filter_properties, get_property, properties_by_area, find_comparables, find_similar_properties, get_price_history
  • Valuation (4): estimate_property_value, estimate_rent_value, get_value_range, compare_to_market
  • Rentals (3): search_rentals, get_rental, rental_market_stats
  • Market (6): market_overview, area_market_stats, price_trends, days_on_market_report, compare_areas, investment_analysis
  • Neighborhood (6): area_report, neighborhood_schools, neighborhood_amenities, area_demographics, walkability_transit, compare_neighborhoods
  • Geo/Commute (5): geocode_address, filter_by_commute, map_links_for_property, directions_to_property, area_boundary_box
  • Map/Distance (3): search_by_radius (mileage-radius search), map_for_listings (GeoJSON + multi-marker map for a result set), drive_time (real Distance Matrix when keyed, else straight-line proxy)
  • Buyer finance (5): mortgage_payment, affordability_estimate, closing_costs_estimate, rent_vs_buy, monthly_cost_of_ownership
  • Analytics (3): compare_listings, new_listings, rank_by_value (deal finder)
  • Place/Data (7): nearby_places (keyless POI links), school_search_links, environmental_risk_links (FEMA/NOAA), commute_shed (isochrone approx), current_mortgage_rates, property_tax_history, ownership_history
  • Monitoring (1): saved_search_diff (new / removed / price-changed since last run)
  • Landlord (6): rent_roll, rental_cash_flow (NOI/DSCR), operating_expense_breakdown, rent_increase_analysis, vacancy_cost, landlord_total_return
  • Investor (6): brrrr_analysis, max_allowable_offer, wholesale_spread, dscr_loan_sizing, portfolio_analysis, flip_analysis
  • Developer (4): land_residual_value, construction_pro_forma, buildable_units, subdivision_analysis
  • Agent/Broker (6): commission_calculator, seller_net_sheet, buyer_cash_to_close, listing_price_recommendation, days_to_sell_estimate, cma_report
  • MCP protocol features (4): generate_listing_description (sampling), guided_buyer_intake (elicitation), bulk_area_analysis (progress + logging), market_snapshot (typed structured output)
  • Saved searches (4): create_saved_search, list_saved_searches, run_saved_search, delete_saved_search
  • System (3): provider_info, refresh_cache, server_stats
  • Investment calculators (12): irr_analysis, npv_analysis, cash_on_cash_return, cap_rate, sensitivity_analysis, monte_carlo_simulation, depreciation_schedule, tax_benefits, capital_gains_tax, refinance_breakeven, str_revenue_estimate, exchange_1031
  • Deal structuring (14): house_hack_analysis, syndication_analysis, portfolio_growth_projection, mortgage_qualification, debt_to_income, compare_loans, construction_loan_analysis, subject_to_analysis, seller_financing_analysis, hard_money_analysis, joint_venture_analysis, property_management_compare, breakeven_occupancy, deal_pipeline
  • External data (8): mortgage_rate_trends (FRED), walk_transit_score (Walk Score), census_demographics (Census ACS), broadband_lookup (FCC), flood_zone (FEMA), multi_stop_commute (Google Distance Matrix), pre_foreclosure_signals (ATTOM), blended_valuation (RentCast + ATTOM)
  • Marketing & export (12): listing_flyer (HTML), social_media_post, landing_page (HTML), comp_grid (CMA grid), qr_code (offline SVG), email_campaign, export_report (CSV/Markdown), staging_suggestions, floor_plan (schematic SVG), virtual_tour (HTML), map_image, community_rating
  • Diagnostics (1): doctor (probe every configured provider/key and report health)
  • Acquisition & distressed (9): assumption_analysis, assumability_check, assumption_breakeven, absentee_owner_check (ATTOM), equity_position_estimate (ATTOM), distressed_deal_analyzer, redemption_period_reference, gov_reo_links, fsbo_search_links
  • Diligence (2): crime_safety (FBI Crime Data Explorer + live estimate when keyed), detect_hoa
  • Financing extras (5): amortization_schedule, rate_buydown_analysis, cash_out_refinance, refi_vs_sell, insurance_estimate
  • Tax (3): property_tax_estimate, cost_segregation_estimate, schedule_e_summary
  • Transaction (2): compare_offers, transaction_timeline
  • Reference (2): str_regulation_check, landlord_tenant_reference
  • Hazard & livability (2): fema_nri_risk (FEMA National Risk Index, 18 hazards), air_quality (EPA AirNow)
  • Meta (1): catalog (in-server tool discovery)

Most tools support response_format="markdown" (default) or "json" and return pagination metadata where applicable; the finance/investor/landlord/ developer calculators and several analytical tools return JSON directly.

MCP protocol features

Beyond tools/resources/prompts, the server demonstrates the newer MCP capabilities, each with a graceful fallback when the client doesn't support it:

  • Completions — argument autocomplete for areas, ZIPs, and property ids (registered via @mcp.completion(); pure logic in suggest_completions).
  • Sampling — generate_listing_description asks the client's LLM to write copy, falling back to a deterministic template.
  • Elicitation — guided_buyer_intake requests missing criteria, falling back to a structured "needs_input" response.
  • Progress + logging — bulk_area_analysis emits report_progress and log events while iterating.
  • Structured output — market_snapshot returns a typed Pydantic model, so the client gets structured content plus a generated output schema.

No new environment variables are required; drive_time's live path reuses the existing GOOGLE_MAPS_API_KEY, and tax/ownership/rates are provider-backed (synthetic under mock, real with a keyed provider).

API keys & where to get them

Copy .env.example to .env and fill in what you need. Everything works with no keys on the mock provider; add keys to unlock real data. Each external tool degrades gracefully (returns a short "set X_API_KEY" note) when its key is absent.

KeyUnlocksCostGet it
RENTCAST_API_KEYListings, search, AVM value/rent, market statsFree tierhttps://app.rentcast.io/app/api
ATTOM_API_KEYProperty records, AVM, tax, ownership, sale history, pre-foreclosureFree trialhttps://api.developer.attomdata.com/
GOOGLE_MAPS_API_KEYReal geocoding, drive times, multi-stop commute, static mapsPay-as-you-go (free credit)https://console.cloud.google.com/google/maps-apis
FRED_API_KEYLive 30/15-yr mortgage rates (mortgage_rate_trends)Freehttps://fredaccount.stlouisfed.org/apikeys
CENSUS_API_KEYCounty demographics (census_demographics)Freehttps://api.census.gov/data/key_signup.html
WALKSCORE_API_KEYWalk/Transit/Bike score (walk_transit_score)Freehttps://www.walkscore.com/professional/api-sign-up.php
FBI_API_KEY(reserved) crime statisticsFreehttps://api.data.gov/signup/

Keyless and always on: FEMA flood-zone lookup (flood_zone), FCC geography (broadband_lookup), Google/OSM map links, and every calculator.

Install & packaging

Run directly (this is what Claude Desktop launches):

python main.py

Install the console script with pipx or run zero-install with uv:

pipx install .                 # provides a `cornerstone-mcp` command
uvx --from . cornerstone-mcp    # zero-install run

Docker (MCP speaks over stdio, so keep stdin open with -i):

docker build -t cornerstone-mcp .
docker run --rm -i --env-file .env cornerstone-mcp

Run the doctor tool any time to verify wiring: it probes RentCast, ATTOM, Google, FRED, Census, and Walk Score and reports which are configured and reachable.

Testing

pip install -r requirements-dev.txt   # runtime deps + pytest + pytest-asyncio
pytest                                # 165 tests, all offline against the mock provider

Extending: add a provider

  1. Subclass RealEstateProvider in providers/yourprovider.py, implement the methods you can serve, and map responses into the models.py dataclasses.
  2. Set name, source_label, and capabilities.
  3. Register it in providers/__init__.get_provider() behind a REALESTATE_PROVIDER value. Unsupported methods can be left to the base class (they raise a clear "not supported by this provider" message that tools surface to the user).

Changelog

See CHANGELOG.md for version history — recent: ATTOM data provider + hybrid enrichment backend and 73 new tools (12 investment calculators, 14 deal-structuring calculators, 8 live external-data tools — FRED, Walk Score, Census, FCC, FEMA, multi-stop commute — 12 marketing/export tools, a doctor self-test, 9 alternative-acquisition tools for assumptions/distressed/REO/FSBO, crime_safety + detect_hoa, and 15 pre-release tools spanning amortization, rate buydowns, cash-out/HELOC, refi-vs-sell, tax estimators, offer comparison, transaction timelines, STR & landlord-tenant references, FEMA NRI, air quality, and a tool catalog), plus live FRED mortgage rates and packaging (pyproject/Docker/CI). Tools: 83 -> 156.

Full tool reference

Every one of the 156 tools - grouped by module, with descriptions and parameters - is documented in docs/TOOLS.md. You can also call the in-server catalog tool to list tools live, or doctor to see which data sources are currently configured.

Feature requests

Cornerstone is actively maintained and I am taking feature requests. If there is a calculation, data source, or workflow you would like added, please open an issue and describe the use case. Pull requests are welcome too - see the provider and tool conventions above.

Contributing

New tools, data providers, and fixes are welcome. See CONTRIBUTING.md for local setup, running the test suite, and the tool and provider conventions to follow.

Support the project

If Cornerstone saved you time or helped you make a real real-estate decision, please consider supporting continued development. Donations are completely optional and always appreciated:

Prefer a different method? Open an issue and I will add it. Thank you for helping keep the project maintained and growing.

Ver o original no GitHub

Bom para

Relacionados