Homecastr MCP Server

Probabilistic home value forecasts for any US address, ZIP, Census tract, county, or state, available as a Model Context Protocol (MCP) server for ChatGPT, Cursor, Claude, Windsurf, and other AI agents.

Quick Start

Remote (no install)

{
  "mcpServers": {
    "homecastr": {
      "url": "https://www.homecastr.com/api/mcp/mcp"
    }
  }
}

Local (stdio)

npx homecastr-mcp-server

MCP Client Config

{
  "mcpServers": {
    "homecastr": {
      "command": "npx",
      "args": ["-y", "homecastr-mcp-server"],
      "env": {
        "HOMECASTR_API_KEY": "hc_demo_public_readonly"
      }
    }
  }
}

Discovery

• Well-known server metadata: https://www.homecastr.com/.well-known/mcp/server.json
• Well-known server card: https://www.homecastr.com/.well-known/mcp/server-card.json
• Discovery mirror: https://www.homecastr.com/.well-known/mcp.json
• Human-readable MCP docs: https://www.homecastr.com/docs/mcp

Environment Variables

| Variable | Required | Default | Description | |---|---|---|---| | HOMECASTR_API_KEY | No | hc_demo_public_readonly | API key. Demo key rate-limited (50 req/hr). Get a free key and docs at homecastr.com/docs. | | HOMECASTR_API_URL | No | https://www.homecastr.com | Override for staging/self-hosted environments. | | WORLDCASTR_API_KEY | No | hc_demo_public_readonly | Worldcastr alias for the same API credential. HOMECASTR_API_KEY takes precedence when both are set. | | WORLDCASTR_API_URL | No | https://worldcastr.com | Set to https://worldcastr.com to use the Worldcastr endpoint. HOMECASTR_API_URL takes precedence when both are set. |

PostHog MCP Analytics

Set POSTHOG_PROJECT_API_KEY to enable MCP tool-call analytics. The server also reads POSTHOG_HOST (default https://us.i.posthog.com) and falls back to NEXT_PUBLIC_POSTHOG_KEY / NEXT_PUBLIC_POSTHOG_HOST if those are already configured in your environment.

Tools (38 HTTP tools, 42 stdio tools)

Forecasts (public - demo key works)

| Tool | Input | Coverage | |---|---|---| | forecast_by_address | address (string), year (optional 2026–2030) | Houston metro | | forecast_by_parcel | acct (tax parcel ID) | FL + Houston | | forecast_by_unit | acct, include_siblings (optional bool) | FL + Houston | | forecast_by_tabblock | geoid (15-digit Census GEOID20) | NYC + Houston | | forecast_by_tract | geoid (11-digit Census GEOID20) | Nationwide (~82K tracts) | | forecast_by_zcta | zcta (5-digit ZIP) | Nationwide (~20K ZCTAs) | | forecast_by_zip3 | zip3 (3-digit ZIP prefix) | Nationwide (6,210 areas) | | forecast_by_county | fips (5-digit county FIPS) | Nationwide | | forecast_by_state | fips (2-digit state FIPS) | All 50 states | | forecast_by_h3_cell | h3_id, year (optional) | Houston metro (legacy) |

Benchmarks & Public Data (public - demo key works)

| Tool | Input | Notes | |---|---|---| | list_benchmark_datasets | phase (optional), asset_class (optional), public_readiness (optional) | Catalog of public-safe benchmark and data assets | | get_benchmark_dataset | asset_id | Resolve one asset to its benchmark/public surface | | get_public_forecast_vintage | vintage_id (optional), support_level (optional), target (optional) | Validated public-vintage tables with provenance | | get_backtest_scores | benchmark_id (optional), target (optional) | Public-safe score summaries such as model-vs-persistence | | get_target_metric_forecast | geoid, target | Aggregate tract target-metric bridge surface; may be deployment-gated | | get_census_bps_county_monthly | year, month, kind, county_fips, state_fips, limit, history, summary (all optional) | Normalized Census BPS county-month permit rows from the public R2-backed permit surface | | get_fast41_projects | project_id, state, status, sector, lead_agency, limit, summary (all optional) | Normalized FAST-41 federal permitting project inventory rows; not a milestone-date settlement oracle until the full dataset is normalized | | get_epa_echo_npdes_sewer_overflows | state, permit_id, event_type, year, min_volume_gallons, with_coordinates, limit, summary (all optional) | Normalized EPA ECHO NPDES current sewer-overflow and bypass event rows; not a settlement oracle until refresh/checksum/replacement-report policy is published | | get_epa_echo_npdes_sewer_overflow_history | state, permit_id, event_type, year, min_volume_gallons, with_coordinates, current_only, include_replaced, limit, summary (all optional) | Normalized EPA ECHO NPDES all-version sewer-overflow and bypass event rows with amendment/replacement history; not a settlement oracle until refresh/checksum/revision policy is published | | get_epa_echo_npdes_outfalls | state, permit_id, status, component, current_violation, cwa_status, with_coordinates, limit, summary (all optional) | Normalized EPA ECHO ICIS-NPDES outfall/facility/permit-status rows; not a settlement oracle until limits, effluent violations, detailed enforcement rows, and refresh/checksum/revision policy are published | | get_epa_echo_npdes_violations | state, permit_id, category, violation_code, rnc_detection_code, rnc_resolution_code, year, has_linked_enforcement, limit, summary (all optional) | Normalized EPA ECHO ICIS-NPDES permit-schedule, compliance-schedule, and single-event violation rows; not a settlement oracle until effluent violations, limits, detailed enforcement rows, refresh/checksum, and revision policy are published |

Canonical Data Discovery (public - demo key works)

| Tool | Input | Notes | |---|---|---| | list_data_assets | data_family (optional), public_status (optional), visibility (optional), inventory_asset (optional) | Canonical 89-row asset catalog across public, metadata-only, restricted, and unavailable surfaces | | get_data_asset | asset_id | Full canonical asset card with contracts, provenance, access policy, and related artifacts | | list_data_sources | data_family (optional), public_status (optional), license_status (optional) | Source-oriented view across provenance manifests, source catalogs, panels, and reference datasets | | get_data_source | source_id | One upstream source record with official URLs, source family, panel links, provenance metadata, and access policy | | get_panel_lineage | panel_id, source_id (optional) | Source-to-panel lineage edges with source roles, join keys, transforms, output fields, and official source URLs | | get_data_coverage | none | Source, official-link, family, geography, resolution, panel-lineage, source-to-geography index, and coverage-map rollup counts | | list_source_coverage_index | source_id (optional), coverage_feature_id (optional), panel_id (optional), coverage_geometry_role (optional), native_boundary_status (optional) | Source-to-geography index rows with coverage feature IDs, reference-boundary metadata, native-boundary review status, official URLs, and geometry redistribution policy | | list_public_records_acquisition | lane_id (optional), source_family (optional), geography (optional), current_status (optional), records_law_gate (optional) | Metadata-only public-records acquisition evidence lanes with durable cloud evidence, public-route checks, records-law gate posture, holdbacks, and next safe action | | get_source_coverage_map | none | Selectable source-coverage GeoJSON layer with public reference boundaries where available, generalized regions elsewhere, source IDs, official URLs, panel links, readiness, license metadata, and geometry notes | | list_data_schemas | data_family (optional), schema_id (optional) | Schema bundle catalog for canonical dataset, panel, forecast, benchmark, and artifact contracts | | get_data_schema | schema_id | Full JSON Schema definition plus referenced families and assets | | get_entity | entity_id, entity_type (optional) | Canonical geography entity metadata with normalized IDs, labels, and parent hierarchy | | get_geography_crosswalk | source_entity_id, source_entity_type (optional), target_entity_type (optional) | Canonical crosswalk rows such as tract-to-county or tract-to-ZCTA | | get_provenance | provenance_id | Reviewed provenance manifest or source ledger with retrieval and publication metadata | | get_data_artifact | artifact_id | Artifact manifest metadata, including format, owner asset, and canonical download path |

Canonical Data Query (public - demo key works)

| Tool | Input | Notes | |---|---|---| | query_observations | entity_id, asset_id (optional), entity_type (optional), metric_id (optional), period_start (optional), period_end (optional) | Canonical observation rows for aggregate-safe histories such as tract ACS target panels | | query_features | entity_id, asset_id (optional), entity_type (optional), metric_id (optional), feature_id (optional), as_of_date (optional), period_start (optional), period_end (optional) | Canonical feature rows with transform metadata and leakage-safe input references | | get_panel_slice | panel_id, entity_id, entity_type (optional), metrics (optional), period_start (optional), period_end (optional) | Canonical multi-metric panel rows for benchmark or training-candidate review | | query_forecasts | entity_id, asset_id (optional), entity_type (optional), metric_id (optional) | Canonical forecast-series records with origin time, horizon points, and training cutoff metadata | | get_forecast_vintage | vintage_id, target (optional) | Canonical same-vintage public forecast series with provenance-heavy benchmark labeling | | get_benchmark_result | benchmark_id, target (optional) | Canonical benchmark result record with standardized score rows and reproducibility references | | get_synthetic_dataset | synthetic_id, entity_type (optional), entity_id (optional), metric_id (optional) | Explicitly labeled synthetic scenario bundle derived from canonical forecasts |

Content & Analytics (real API key required for last two)

| Tool | Input | Notes | |---|---|---| | get_narrative | geoid, level (optional: state|county|city|tract) | AI-generated market narrative | | get_county_outlook | fips (5-digit county FIPS) | Pre-computed appreciation + trajectory | | get_permit_zoning_readiness | source_id, market_id, summary (all optional) | Permit/zoning source evidence and market-readiness gates; use get_census_bps_county_monthly, get_fast41_projects, get_epa_echo_npdes_sewer_overflows, get_epa_echo_npdes_sewer_overflow_history, get_epa_echo_npdes_outfalls, and get_epa_echo_npdes_violations for currently exposed normalized row surfaces | | list_training_runs | jurisdiction (optional), year (optional), limit (optional) | ML training history | | get_analytics_events | event_name (optional), page_path (optional), days (optional) | Product event stats |

Output Format

Every forecast tool returns probabilistic bands:

• P10 - pessimistic downside (10th percentile)
• P25 - conservative estimate
• P50 - median expected value
• P75 - optimistic estimate
• P90 - upside scenario (90th percentile)

Plus appreciation %, growth $, and a multi-year fan chart.

Example Prompts

• "What's the 5-year home price forecast for 5000 Westheimer Rd, Houston TX?"
• "Compare the forecast for ZIP 77056 vs 10001 over the next 3 years."
• "What's the P90 appreciation for Harris County TX by 2030?"
• "Get the market narrative for Census tract 48201231400."
• "List the phase_1 benchmark datasets and tell me which ones are launch-ready."
• "Get the Arizona OEO Maricopa 2022 public forecast vintage for total_population."
• "List all draft input_panel assets and tell me which ones are training candidates."
• "Load the source coverage map and show which official sources are associated with Phoenix / Maricopa / Pinal."
• "List source coverage-index rows for Phoenix and show which sources have public reference boundaries versus native-boundary terms review."
• "List public-records acquisition lanes for utility infrastructure where the request gate is closed, and summarize the holdbacks."
• "Show me the canonical schema for hc.panel_row.v1."
• "Get the provenance manifest for provenance.arizona_archive_status_ledger."

Links

• Developer docs
• MCP docs
• REST reference
• OpenAPI spec
• Well-known server metadata
• Well-known server card
• RapidAPI

License

MIT