MCP API Documentation

Search Saudi rental or sale property listings with filters. Returns paginated results. Prices are in SAR.

Get full details for a specific property listing by its ID.

Find similar nearby listings for price comparison. Returns listings within ~5km with same property type and similar bedroom count (+/-1).

Get price change history for a listing. Shows how the price evolved over time, total price change percentage, and days on market.

Find listings priced below their neighborhood median — best deals. Returns listings sorted by discount percentage (biggest savings first).

Fetch full details for multiple listings by their IDs in one call (max 200). Use when comparing specific listings.

Count listings matching filters without fetching listing data. Returns just { total: number }.

Get price distribution histogram. Returns 30 buckets with counts, plus median and mean.

Get area (sqm) distribution histogram. Returns 30 buckets with counts, plus median and mean.

Get market context for a specific listing: price/area percentiles, neighborhood comparison, and bedroom price chart.

Compare 2-5 neighborhoods side by side. Returns median price, area, price/sqm, price range (P25-P75), amenity percentages, property mix, and bedroom breakdown for each.

Get a high-level market overview for a city: total listings, median price, breakdown by property type, top neighborhoods, source coverage, and data freshness.

Get monthly price trends for 1-5 neighborhoods over time. Returns median price, P25/P75 range, and listing count per month.

Calculate gross rental yield for a neighborhood or city. Returns yield percentage, listing counts, and top 10 neighborhoods by yield when no neighborhood specified.

Get new listing volume trends: this week vs last week, this month vs last month, with percentage changes and total active count.

Count stale listings (on market 30/60/90+ days) as an oversupply signal. Returns stale counts, percentages, and a freshness score.

Get median price and listing count for every neighborhood in a city, sorted by median price descending. Works for both rent and sale.

List all neighborhoods in a city with Arabic and English names.

Get districts/directions of a city with their neighborhoods. Note: data from external API, may be slower.

Get points of interest near a neighborhood. Returns up to 6 POIs sorted by distance.

Get listings within geographic bounds. Result count scales with zoom level.

Get points of interest within geographic bounds. Returns empty if zoom < 10.

Search off-plan and ready real estate development projects. Filter by developer, type, neighborhood, features, banks, and price.

Get full details for a development project by ID. Returns all project fields plus all its unit listings.

List all real estate developers with active projects in a city. Use to get valid developer names for search_projects.

Search individual units within development projects. Filter by bedrooms, bathrooms, area, price, developer, and project type.