Casafari MCP

The Casafari MCP server exposes Casafari's real estate data to AI agents over the [Model Context Protocol](https://modelcontextprotocol.io). Every entry below is an MCP **tool**, not an HTTP endpoint: an agent calls it by name with a JSON payload matching the tool's input schema. ## Connecting Point any MCP client at `https://mcp.casafari.com/` over Streamable HTTP. The server is an OAuth 2.1 resource server: clients discover the authorization server automatically through the protected-resource metadata (RFC 9728) and obtain a token themselves — interactive clients via authorization code with PKCE, unattended agents via client credentials. Clients that accept a remote MCP server directly (Claude, ChatGPT) need only the URL and will run the authorization flow on their own. Clients configured from a file take: ```json { "mcpServers": { "casafari": { "type": "http", "url": "https://mcp.casafari.com/" } } } ``` ## Tool names Tools are grouped by server and surface as `<group>_<tool>` — always call a tool by its full name. Which tools a token may call depends on the access granted to it, so a connected agent may see fewer tools than are documented here.

Machine-readable catalogue: /mcp/openapi.json

Comparables MCP Server

Comparables: comparable properties and an estimated price range for one home. Call get-comparables with a location_boundary around the home (a circle around a target point given as coordinates, an address or a Spanish cadastral reference, or a closed polygon), the operation (sale or rent) and the home's type, bedrooms and size as the tool asks. It returns the matched comparables ranked by relevance (active listings, past sales and rentals, and registry records), statistics for the set and estimated fair, quick-sale and premium prices. Use a tight radius (0.5-1 km) in cities and a wider one (2-5 km) in rural areas.

comps_get-comparables — Get Comparables: # Tool: get-comparables ## Description Retrieves **comparable real estate properties** and **AI-powered market valuations** using the Casafari Comparables Engine. The tool analyzes: - **Active listings** – current market offerings - **Historical transactions** – past sales and rentals - **Verified DVF data** – official property transfer records Returns: - **Matched comparable properties** ranked by relevance - **Aggregated market statistics** (median prices, DOM, listing velocity) - **Estimated price ranges**: fair market value, quick-sale price, premium pricing ## Primary Use Cases | Use Case | Description | |----------|-------------| | **Property Valuation** | Price a listing based on real market data | | **Comp Analysis** | Find similar properties for BPO/CMA reports | | **Market Research** | Analyze local trends, absorption rates, pricing dynamics | | **Investment Modeling** | Assess fair value vs. asking price spreads | | **Historical Trends** | Track price evolution using sold_or_rented_after filter | ## Key Capabilities ### Advanced Filtering - **Property attributes**: type, bedrooms, bathrooms, size, condition - **Structural features**: floor level, orientation, views, parking, storage - **Quality markers**: construction year, energy rating, renovation status - **Characteristic logic**: must-have / nice-to-have / exclude lists - **Temporal filters**: sold/rented after specific date ### Spatial Precision Uses a **circle boundary** (target point + radius in kilometers) or a **closed polygon** of geo-points to ensure all comparables reflect the same micro-market conditions. The target point accepts coordinates, an address, or a Spanish cadastral reference. ### Output Intelligence - **Property-level data**: individual comp details with photos, descriptions, pricing history - **Registry data**: DVF records (dvf_results) and notarial transactions (transactional_data) - **Market-level stats**: aggregated insights (median $/sqm, average DOM, inventory levels) - **Valuation estimates**: algorithmic price recommendations based on comp set ## Pro Tips - Use tight radius (0.5-1 km) for urban areas, wider (2-5 km) for rural - Combine sold_or_rented_after with recent date for "hot market" analysis - Leverage characteristic filters to match unique property features (e.g., sea views, penthouse, ground floor) - Check both active listings AND sold comps for complete market picture --- **Powered by Casafari's proprietary matching algorithm** – trained on millions of European property transactions.

Area Insights MCP Server

Area Insights: how a real estate market behaves in an area, from active listings. Start with get_location_typeahead to turn a place name (in English) into a location_id; most tools take location ids or a circle, never a name. get_time_series_data returns a metric (average price, price per m², new listings, sold or rented, available stock, price changes) per week, month, quarter or year; get_time_series_operations computes growth and volatility on one such series (mean, delta_pct, cagr, std, cv and more). get_price_distribution, get_bedrooms_distribution and get_time_on_market_distribution split an area by price band, bedroom count or time on market. get_heatmap compares the districts inside a location for one metric. get_current_datetime gives today's date for building date ranges. Compare property types with separate calls, one type_group each.

area_get_current_datetime — Get Current Datetime: # Tool: `get_current_datetime` ## Description Returns the current system date and time. ## Returns ```json { "current_datetime": "2025-10-06T12:45:00.000000" } ``` | Key | Type | Description | |------|------|-------------| | `current_datetime` | `str` | Local system date and time in ISO format. | ## Example Usage ```python result = await call_tool("get_current_datetime") print(result["current_datetime"]) ```
area_get_time_series_data — Get Time Series Data: # Tool: `get_time_series_data` ## Description Retrieve **time series data** for the real estate market. Each data point in the series represents an aggregated metric (`data_point`) for a specific period, defined by the chosen `date_interval` and property filters. This tool provides consistent, interval-based historical data for various real estate indicators. ## Use Cases Retrieve historical market information, such as: - Average property prices. - Average price per square meter. - Number of properties sold or rented over time. - Number of newly listed properties. - Number of properties available on the market. - Number of price increases or decreases for listings. ## Parameters | Name | Type | Required | Description | |------|------|-----------|--------------| | `request_data` | `MCPTimeSeriesRequestSchema` | Yes | Defines filters, time interval, and data metric (`data_point`) for aggregation. | ### Filter highlights - `data_point`: defines **which metric** to retrieve (e.g. price, listings, sold count, etc.). - `date_interval`: defines **the frequency** of data points in the response (`WEEK`, `MONTH`, `QUARTER`, `YEAR`). - `custom_location_boundary`: spatial boundary (circle or list of location IDs). - `type_group`: group of property types to analyze. - `business_type`: `"sale"` or `"rent"`. - `exclude_outliers`: optionally exclude statistical outliers from the results. - optional property filters: price range, area, bedrooms, bathrooms, etc. ## Important Notes - If you need to compare different property types, send **separate requests** for each type group. - For broader analyses, prefer using `AVERAGE_PRICE_PER_SQM` over total price. - You can reuse the same filters with different `data_point` values to analyze multiple aspects of the market (e.g. compare new listings vs. sold properties). - Use the `exclude_outliers` flag to remove extreme values and improve analytical accuracy. ## Returns ```json [ { "date_start": "2024-01-01", "value": 4350.5 } ]
area_get_time_series_operations — Get Time Series Operations: # Tool: `get_time_series_operations` ## Description Performs analytical **time-series operations** (e.g., `mean`, `delta_pct`, `CAGR`, `cv`, `std`, etc.) for a **single geographic or analytical segment** using real-estate historical data. This tool enables focused analysis of **real estate market dynamics** over time — such as prices, listings, or sales — within one defined location or subset. ## Purpose Designed for analytical scenarios such as: - Tracking how property prices evolve in a specific area. - Measuring growth trends (e.g., CAGR, percentage deltas). - Evaluating volatility using standard deviation or coefficient of variation. - Studying local market activity over a given period. ## Input (`request_data`) Expects an instance of `MCPTimeSeriesOperationsRequestSchema`, which includes: - **`segment`** → a single `MCPTimeSeriesRequestSchema` object defining the geographic or analytical subset. - **`operations`** → list of time-series operations (`TimeSeriesOperationEnum`) to compute. `MCPTimeSeriesRequestSchema` includes: - `custom_location_boundary`: spatial boundary (circle or list of location IDs). - `data_point`: metric to analyze (e.g. `AVERAGE_PRICE_PER_SQM`, `SOLD_COUNT`, `NEW_LISTED_COUNT`). - `date_interval`: aggregation interval (`WEEK`, `MONTH`, `QUARTER`, or `YEAR`). - `date_range`: start and end of the analysis period. - Optional property filters (price, area, rooms, construction year, etc.). - `exclude_outliers`: whether to exclude statistical outliers. > **Analytical consistency rule:** The analytical context (data_point, date_interval, business_type, etc.) must remain consistent within the request. The `segment` may only redefine `custom_location_boundary` and `alias` relative to the base filter. ## Operations Supported operations from `TimeSeriesOperationEnum` include: - `mean` — average value across the time range. - `delta_pct` — percentage change between the first and last data points. - `cagr` — compound annual growth rate. - `std` — standard deviation. - `cv` — coefficient of variation. - (plus others defined in the enum). ## LLM Behavior - On success → returns a **single analytical result** (`MCPTimeSeriesUnitResponseSchema`) containing computed metrics for the requested segment. - On error → raises a `ToolError` with an error message. ## Example Success Response ```json { "alias": "Madrid Center", "date_start": "2020-01-01", "date_end": "2024-01-01", "date_interval": "MONTH", "total_of_data_points": 48, "results": [ {"operation": "mean", "value": 3200.5}, {"operation": "delta_pct", "value": 12.4}, {"operation": "cagr", "value": 0.032} ] } ``` ## Example Error Response ``` ToolError: No data found for the specified segment. ``` ## Example Use Cases - Analyze **average price per m²** in a specific city or district. - Measure **sales growth** over several years. - Evaluate **rental market volatility**. - Assess **seasonal dynamics** of listings or sales activity. ## Summary `get_time_series_operations` retrieves **aggregated real-estate time-series data** for a defined location or segment and computes selected analytical operations. It provides a structured, quantitative summary of market trends and changes for a single region or subset.
area_get_price_distribution — Get Price Distribution: # Tool: `get_price_distribution` ## Description Returns a **distribution of property prices** based on the provided filters. Each record represents a price interval and the number of properties within that interval. ## Parameters | Name | Type | Required | Description | |------|------|-----------|--------------| | `request_data` | `MCPPriceDistributionRequestSchema` | Yes | Configuration for price distribution filtering. | ### Filter highlights - `type_group`: group of estate types (e.g., apartment, house) - `business_type`: `"sale"` or `"rent"` - `price_range`: numeric price range filter - `exclude_outliers`: optional flag to exclude statistical outliers ## Returns ```json [ { "lower_bound": 100000, "upper_bound": 150000, "properties_count": 42, "is_mean": false } ] ``` | Field | Type | Description | |--------|------|-------------| | `lower_bound` | `int` | Lower price boundary | | `upper_bound` | `int` | Upper price boundary | | `properties_count` | `int` | Number of properties in the range | | `is_mean` | `bool` | Indicates whether the range includes the mean price | ## Example Request ```json { "custom_location_boundary": { "circle": { "target_point": {"latitude": 48.8566, "longitude": 2.3522}, "distance": 10000 } }, "type_group": "apartment", "business_type": "sale", "price_range": {"min": 100000, "max": 500000}, "exclude_outliers": true } ```
area_get_bedrooms_distribution — Get Bedrooms Distribution: # Tool: `get_bedrooms_distribution` ## Description Returns a **distribution of properties grouped by the number of bedrooms**. Each record includes total listings count, average price, and average price per square meter. ## Business Context Useful for analyzing pricing differences and market concentration based on bedroom count — ideal for residential market segmentation. ## Parameters | Name | Type | Required | Description | |------|------|-----------|--------------| | `request_data` | `MCPBedroomsDistributionRequestSchema` | Yes | Filter configuration for bedroom-based distribution. | ### Filter highlights - `type_group`: property type group (e.g., apartment, house) - `business_type`: `"sale"` or `"rent"` - `custom_location_boundary`: geographical boundary filter - `bedrooms_range`: range of bedroom counts - `exclude_outliers`: optional flag to remove statistical outliers ## Returns ```json [ { "bedrooms": "2", "properties_count": 324, "average_price": 245000.0, "average_price_per_sqm": 5200.0 } ] ``` | Field | Type | Description | |--------|------|-------------| | `bedrooms` | `str` | Bedroom count label | | `properties_count` | `int` | Number of properties | | `average_price` | `float` | Average property price | | `average_price_per_sqm` | `float` | Average price per square meter | ## Example Request ```json { "custom_location_boundary": { "circle": { "target_point": {"latitude": 48.8566, "longitude": 2.3522}, "distance": 10000 } }, "type_group": "apartment", "business_type": "sale", "bedrooms_range": {"min": 1, "max": 4}, "exclude_outliers": true } ```
area_get_time_on_market_distribution — Get Time on Market Distribution: # Tool: `get_time_on_market_distribution` ## Description Returns a **distribution of properties by their time on the market**, grouped by price intervals. Each record contains average listing duration and property count. ## Business Context Useful for evaluating **market liquidity** and **demand efficiency**, identifying price segments where listings sell faster or remain longer. ## Parameters | Name | Type | Required | Description | |------|------|-----------|--------------| | `request_data` | `MCPTimeOnMarketDistributionRequestSchema` | Yes | Defines filters for listing duration analysis. | ### Filter highlights - `type_group`: property type group - `business_type`: `"sale"` or `"rent"` - `price_range`: price interval boundaries - `date_range`: date range for the active listing period - `exclude_outliers`: optional flag to exclude statistical outliers ## Returns ```json [ { "lower_bound": 100000, "upper_bound": 199999, "days_on_market": 45, "months_on_market": 1.5, "properties_count": 120 } ] ``` | Field | Type | Description | |---------------|-------|------------| | `lower_bound` | `int` | Lower price limit | | `upper_bound` | `int` | Upper price limit | | `days_on_market` | `int` | Average number of active days | | `months_on_market` | `float` | Average duration in months | | `properties_count` | `int` | Number of listings in the group | ## Example Request ```json { "custom_location_boundary": { "circle": { "target_point": {"latitude": 41.3851, "longitude": 2.1734}, "distance": 20000 } }, "type_group": "apartment", "business_type": "sale", "price_range": {"min": 100000, "max": 1000000}, "date_range": {"min": "2024-01-01", "max": "2024-12-31"}, "exclude_outliers": true } ```
area_get_heatmap — Get Heatmap: # Tool: `get_heatmap` ## Description Generate an **area heatmap** showing property distribution and price dynamics across geographic areas. This tool aggregates **active real estate listings** for the child locations of the given `location_id` (e.g., districts of a city), returning the selected `data_point` metric for each of them. It supports a wide range of property filters, including estate type, price range, construction year, and location hierarchy. ## Use Cases Retrieve geographic insights for real estate analytics: - Visualize market activity intensity across a city or region. - Identify hotspots of high property density or high average price. - Compare neighborhoods based on average price per sqm. - Analyze supply distribution and property trends over time. - Combine with time-series data to understand historical evolution by area. ## Parameters | Name | Type | Required | Description | |------|------|-----------|--------------| | `request_data` | `MCPHeatMapRequestSchema` | Yes | Defines filters, metrics, and date range for heatmap generation. | ## Important Notes - Only **ACTIVE** listings are included. - The tool automatically resolves **child locations** (e.g., neighborhoods within a city). - If no matching data is found, a `ToolError` will be raised. - Use returned data for **map visualization** or **spatial analytics dashboards**. ## Returns ```json [ { "location_id": 12345, "location_name": "Lisbon", "value": 5200.5 } ] ``` Each item represents one geographic unit with aggregated metric value.
area_get_location_typeahead — Get Location Typeahead: Retrieve typeahead suggestions for a given location name. Use case: Retrieve typeahead suggestions to get location_id for different requests. Important notes: - If there is more than one location with the same name, and it's not clear which one is correct - specify more information / symbols in the request. - The `location_name` should be a valid location name in English.