homecastr-mcp-server

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