Назад в консоль разработчикаВ разработке

Справочник API

Каждый инструмент, который предоставляет MCP-сервер Secrets.RealEstate — параметры, покрытие и пример ответа.

16: инструментов
8: официальных открытых наборов данных
96: департаментов — вся Франция

Подключение

Добавьте размещённый сервер в свой MCP-клиент (Claude Code, Cursor и другие). Замените заполнитель ключом из консоли разработчика.

claude mcp add secrets-realestate \
  --transport http https://secrets.realestate/mcp \
  --header "X-API-Key: sk_live_…"

claude_desktop_config.json

{
  "mcpServers": {
    "secrets-realestate": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://secrets.realestate/mcp",
        "--header",
        "X-API-Key: sk_live_…"
      ]
    }
  }
}

Каждый запрос должен содержать ваш ключ в заголовке X-API-Key. Анонимного доступа нет — каждый вызов привязан к вашему аккаунту и тарифу. Developer API требует платного тарифа и одобрения администратора.

Соглашения

Каждый инструмент объявляет эти MCP-аннотации:

readOnlyHint — никогда не меняет твои данные — каждый вызов только читает
idempotentHint — одинаковый вызов возвращает одинаковый результат, поэтому его безопасно повторять
openWorldHint — читает живые внешние данные, поэтому результаты могут меняться со временем

Местоположение задаётся координатами (lat/lng) — сначала определите адрес через geocode_address.
Передайте lang (en, de, fr, it, ru, es) для локализации текстовых полей; по умолчанию en.
Инструменты со списками (search_properties, get_my_listings) разбиваются на страницы через page и size.
Поля ответа — в snake_case.
Все инструменты сейчас охватывают Францию — за пределами Франции или при недоступном провайдере инструмент возвращает пустой результат или null, но не ошибку.

Инструменты

Глубокое покрытие по всем департаментам Франции, объединённое из восьми официальных открытых наборов данных — BDNB, IRIS, SSMSI, GeoRisques, Hub'Eau, Éducation IVAL, OpenStreetMap и DVF. Другие рынки — позже.

Поиск и данные

search_properties

Search property listings on Secrets.RealEstate by city, type, price, size and bedrooms (paginated). Use when the user wants to find or browse properties matching criteria.

Параметры

Параметр	Тип	Описание	Обязательный
`city`	`string`	City to search in, e.g. Nice.	Нет
`property_type`	`string`	Property type, e.g. apartment or house.	Нет
`price_min`	`integer`	Minimum price.	Нет
`price_max`	`integer`	Maximum price.	Нет
`size_min`	`integer`	Minimum living area in square metres.	Нет
`size_max`	`integer`	Maximum living area in square metres.	Нет
`bedrooms`	`integer`	Minimum number of bedrooms.	Нет
`page`	`integer`	Zero-based page number. Defaults to 0.	Нет
`size`	`integer`	Page size, 1-100. Defaults to 10.	Нет

Возвращает

Поле	Тип	Описание
`items`	`array`	Listings on this page.
`property_id`	`integer`	Listing id.
`property_type`	`string`	Property type, e.g. apartment or house.
`price_amount`	`number`	Asking price.
`price_currency`	`string`	ISO currency code, e.g. EUR.
`monthly_fees`	`number`	Monthly charges / co-ownership fees.
`size_sqm`	`integer`	Living area in square metres.
`size_usable_sqm`	`integer`	Usable area in square metres.
`room_count`	`integer`	Total rooms.
`bedroom_count`	`integer`	Bedrooms.
`bathroom_count`	`integer`	Bathrooms.
`floor_level`	`integer`	Floor the unit is on.
`total_floors`	`integer`	Floors in the building.
`plot`	`integer`	Plot / land area in square metres.
`condition`	`string`	Property condition.
`elevator`	`boolean`	Has an elevator.
`garage_spaces`	`integer`	Number of garage / parking spaces.
`pool`	`boolean`	Has a pool.
`furnished`	`boolean`	Sold furnished.
`balcony`	`boolean`	Has a balcony.
`terrace`	`boolean`	Has a terrace.
`energy_rating`	`string`	DPE energy class, A to G.
`ghg_class`	`string`	Greenhouse-gas class, A to G.
`energy_kwh_m2_year`	`integer`	Energy use, kWh/m2/year.
`ghg_kg_co2_m2_year`	`integer`	Emissions, kg CO2/m2/year.
`heating_type`	`string`	Heating type.
`year_built`	`integer`	Construction year.
`street`	`string`	Street name (null if the listing hides its address).
`house_number`	`string`	House number (null if the listing hides its address).
`postal_code`	`string`	Postal code.
`city`	`string`	City.
`state`	`string`	Region or state.
`country`	`string`	Country name.
`country_code`	`string`	ISO country code.
`latitude`	`number`	Latitude (null if the listing hides its address).
`longitude`	`number`	Longitude (null if the listing hides its address).
`listing_url`	`string`	Source listing URL.
`created_date`	`string`	When the listing was saved (ISO date).
`total`	`integer`	Total matching listings.
`page`	`integer`	Zero-based page number.
`size`	`integer`	Page size.

geocode_address

Resolve an address or place name to coordinates (latitude/longitude), city and country. Use whenever the user gives an address or place, asks where something is, wants to locate or pin a property, or needs lat/lon before any other analysis. France is covered in depth; other areas still resolve but have limited downstream data.

Параметры

Параметр	Тип	Описание	Обязательный
`query`	`string`	Address or place to locate, for example 12 rue de Rivoli, Paris.	Да
`lang`	`string`	Response language: en, de, fr, it, ru or es. Defaults to en.	Нет
`limit`	`integer`	Maximum number of results, 1-10. Defaults to 5.	Нет

Возвращает

Поле	Тип	Описание
`latitude`	`number`	Latitude (WGS84).
`longitude`	`number`	Longitude (WGS84).
`display_name`	`string`	Full formatted address.
`city`	`string`	City.
`state`	`string`	Region or state.
`country`	`string`	Country name.
`country_code`	`string`	ISO 3166-1 alpha-2 country code, e.g. fr.
`result_type`	`string`	Match granularity, e.g. house, street, city.

get_listing

Get the facts for a single property listing by its id — price, type, size, rooms, location, energy rating. Use the id returned by search_properties or get_my_listings.

Параметры

Параметр	Тип	Описание	Обязательный
`property_id`	`integer`	The listing id (from search_properties or get_my_listings).	Да

Возвращает

Поле	Тип	Описание
`property_id`	`integer`	Listing id.
`property_type`	`string`	Property type, e.g. apartment or house.
`price_amount`	`number`	Asking price.
`price_currency`	`string`	ISO currency code, e.g. EUR.
`monthly_fees`	`number`	Monthly charges / co-ownership fees.
`size_sqm`	`integer`	Living area in square metres.
`size_usable_sqm`	`integer`	Usable area in square metres.
`room_count`	`integer`	Total rooms.
`bedroom_count`	`integer`	Bedrooms.
`bathroom_count`	`integer`	Bathrooms.
`floor_level`	`integer`	Floor the unit is on.
`total_floors`	`integer`	Floors in the building.
`plot`	`integer`	Plot / land area in square metres.
`condition`	`string`	Property condition.
`elevator`	`boolean`	Has an elevator.
`garage_spaces`	`integer`	Number of garage / parking spaces.
`pool`	`boolean`	Has a pool.
`furnished`	`boolean`	Sold furnished.
`balcony`	`boolean`	Has a balcony.
`terrace`	`boolean`	Has a terrace.
`energy_rating`	`string`	DPE energy class, A to G.
`ghg_class`	`string`	Greenhouse-gas class, A to G.
`energy_kwh_m2_year`	`integer`	Energy use, kWh/m2/year.
`ghg_kg_co2_m2_year`	`integer`	Emissions, kg CO2/m2/year.
`heating_type`	`string`	Heating type.
`year_built`	`integer`	Construction year.
`street`	`string`	Street name (null if the listing hides its address).
`house_number`	`string`	House number (null if the listing hides its address).
`postal_code`	`string`	Postal code.
`city`	`string`	City.
`state`	`string`	Region or state.
`country`	`string`	Country name.
`country_code`	`string`	ISO country code.
`latitude`	`number`	Latitude (null if the listing hides its address).
`longitude`	`number`	Longitude (null if the listing hides its address).
`listing_url`	`string`	Source listing URL.
`created_date`	`string`	When the listing was saved (ISO date).

get_my_listings

List the properties saved in the caller's own account (owner-scoped, paginated). Use when the user asks about their properties, their listings, properties they saved or added, or wants to review their own portfolio. Requires an authenticated caller.

Параметры

Параметр	Тип	Описание	Обязательный
`page`	`integer`	Zero-based page number. Defaults to 0.	Нет
`size`	`integer`	Page size, 1-100. Defaults to 10.	Нет

Возвращает

Поле	Тип	Описание
`items`	`array`	Listings on this page.
`property_id`	`integer`	Listing id.
`property_type`	`string`	Property type, e.g. apartment or house.
`price_amount`	`number`	Asking price.
`price_currency`	`string`	ISO currency code, e.g. EUR.
`monthly_fees`	`number`	Monthly charges / co-ownership fees.
`size_sqm`	`integer`	Living area in square metres.
`size_usable_sqm`	`integer`	Usable area in square metres.
`room_count`	`integer`	Total rooms.
`bedroom_count`	`integer`	Bedrooms.
`bathroom_count`	`integer`	Bathrooms.
`floor_level`	`integer`	Floor the unit is on.
`total_floors`	`integer`	Floors in the building.
`plot`	`integer`	Plot / land area in square metres.
`condition`	`string`	Property condition.
`elevator`	`boolean`	Has an elevator.
`garage_spaces`	`integer`	Number of garage / parking spaces.
`pool`	`boolean`	Has a pool.
`furnished`	`boolean`	Sold furnished.
`balcony`	`boolean`	Has a balcony.
`terrace`	`boolean`	Has a terrace.
`energy_rating`	`string`	DPE energy class, A to G.
`ghg_class`	`string`	Greenhouse-gas class, A to G.
`energy_kwh_m2_year`	`integer`	Energy use, kWh/m2/year.
`ghg_kg_co2_m2_year`	`integer`	Emissions, kg CO2/m2/year.
`heating_type`	`string`	Heating type.
`year_built`	`integer`	Construction year.
`street`	`string`	Street name (null if the listing hides its address).
`house_number`	`string`	House number (null if the listing hides its address).
`postal_code`	`string`	Postal code.
`city`	`string`	City.
`state`	`string`	Region or state.
`country`	`string`	Country name.
`country_code`	`string`	ISO country code.
`latitude`	`number`	Latitude (null if the listing hides its address).
`longitude`	`number`	Longitude (null if the listing hides its address).
`listing_url`	`string`	Source listing URL.
`created_date`	`string`	When the listing was saved (ISO date).
`total`	`integer`	Total matching listings.
`page`	`integer`	Zero-based page number.
`size`	`integer`	Page size.

Рынок

get_comparable_sales

Recent comparable sold properties near a location (official DVF records) with price, size and a liquidity score. France only. Pass coordinates from geocode_address.

Параметры

Параметр	Тип	Описание	Обязательный
`lat`	`number`	Latitude (WGS84). Obtain it from geocode_address.	Да
`lng`	`number`	Longitude (WGS84). Obtain it from geocode_address.	Да
`lang`	`string`	Response language: en, de, fr, it, ru or es. Defaults to en.	Нет

Возвращает

Поле	Тип	Описание
`comparables`	`array`	Recent nearby sales (DVF).
`date`	`string`	Sale date (ISO).
`price`	`integer`	Sale price.
`price_per_sqm`	`integer`	Price per square metre.
`size_sqm`	`integer`	Living area in square metres.
`object_type`	`string`	Property type.
`transaction_type`	`string`	Transaction type.
`latitude`	`number`	Latitude (WGS84).
`longitude`	`number`	Longitude (WGS84).
`liquidity`	`object`	Market liquidity for the area.
`score`	`integer`	Liquidity score (0-100).
`grade`	`string`	Liquidity grade.
`total_transactions`	`integer`	Transactions in the sample.
`annual_volume`	`integer`	Approximate sales per year.
`price_variation`	`number`	Price dispersion.
`distinct_types`	`integer`	Distinct property types seen.

get_price_trends

Price-per-square-metre trend history for a location (official DVF sale records). France only. Pass coordinates from geocode_address.

Параметры

Параметр	Тип	Описание	Обязательный
`lat`	`number`	Latitude (WGS84). Obtain it from geocode_address.	Да
`lng`	`number`	Longitude (WGS84). Obtain it from geocode_address.	Да
`lang`	`string`	Response language: en, de, fr, it, ru or es. Defaults to en.	Нет

Возвращает

Поле	Тип	Описание
`currency`	`string`	ISO currency code.
`series`	`array`	One series per asset type.
`name`	`string`	Series name (asset type).
`points`	`array`	Yearly price-per-sqm points.
`year`	`integer`	Year.
`value`	`integer`	Price per square metre.

get_location_rating

Location rating for a point: mean price, net rent and related neighbourhood market metrics. France only. Pass coordinates from geocode_address.

Параметры

Параметр	Тип	Описание	Обязательный
`lat`	`number`	Latitude (WGS84). Obtain it from geocode_address.	Да
`lng`	`number`	Longitude (WGS84). Obtain it from geocode_address.	Да
`lang`	`string`	Response language: en, de, fr, it, ru or es. Defaults to en.	Нет

Возвращает

Поле	Тип	Описание
`currency`	`string`	ISO currency code.
`description`	`string`	Long description of the location market.
`summary`	`string`	Short summary.
`last_update`	`string`	Date the figures were last updated (ISO).
`summaries`	`array`	Per-asset-type metrics.
`asset_type`	`string`	Asset type.
`price_per_sqm`	`integer`	Mean sale price per square metre.
`rent_per_sqm`	`number`	Mean net rent per square metre.
`grade`	`string`	Grade for the asset type.

Локация и окружение

get_air_quality

Air-quality index and grade for a location. Pass coordinates from geocode_address.

Параметры

Параметр	Тип	Описание	Обязательный
`lat`	`number`	Latitude (WGS84). Obtain it from geocode_address.	Да
`lng`	`number`	Longitude (WGS84). Obtain it from geocode_address.	Да
`lang`	`string`	Response language: en, de, fr, it, ru or es. Defaults to en.	Нет

Возвращает

Поле	Тип	Описание
`aqi`	`number`	Air-quality index.
`grade`	`string`	Air-quality grade (A to G).

get_seasonal_climate

Seasonal temperature / climate profile for a location. Pass coordinates from geocode_address.

Параметры

Параметр	Тип	Описание	Обязательный
`lat`	`number`	Latitude (WGS84). Obtain it from geocode_address.	Да
`lng`	`number`	Longitude (WGS84). Obtain it from geocode_address.	Да
`lang`	`string`	Response language: en, de, fr, it, ru or es. Defaults to en.	Нет

Возвращает

Поле	Тип	Описание
`sunny_days`	`integer`	Sunny days per year.
`seasons`	`array`	Per-season temperature summary.
`season`	`string`	Season: winter, spring, summer or autumn.
`summary`	`string`	Short text summary.
`min_celsius`	`number`	Typical low temperature (Celsius).
`max_celsius`	`number`	Typical high temperature (Celsius).

get_neighborhood

Living environment for a location: amenities, schools, leisure, safety and water quality. France only. Pass coordinates from geocode_address.

Параметры

Параметр	Тип	Описание	Обязательный
`lat`	`number`	Latitude (WGS84). Obtain it from geocode_address.	Да
`lng`	`number`	Longitude (WGS84). Obtain it from geocode_address.	Да
`lang`	`string`	Response language: en, de, fr, it, ru or es. Defaults to en.	Нет

Возвращает

Поле	Тип	Описание
`tabs`	`array`	One entry per environment domain.
`category`	`string`	Domain, e.g. amenities, schools, safety.
`grade`	`string`	Grade for the domain (A to G).
`badges`	`array`	Highlight labels.
`text`	`string`	Short description.

get_noise

Estimated baseline noise level for a location, in decibels. Pass coordinates from geocode_address.

Параметры

Параметр	Тип	Описание	Обязательный
`lat`	`number`	Latitude (WGS84). Obtain it from geocode_address.	Да
`lng`	`number`	Longitude (WGS84). Obtain it from geocode_address.	Да
`lang`	`string`	Response language: en, de, fr, it, ru or es. Defaults to en.	Нет

Возвращает

Поле	Тип	Описание
`base_noise`	`integer`	Estimated baseline noise level in decibels.

Insights

get_building_insights

Full building report for a location: categorised buyer insights (energy/DPE, structural, regulatory, and natural/technological risks such as flood, seismic, clay and radon), each with severity, detail, a recommendation, the applicable regulation and its data source and confidence, plus an overall risk score. Use for due diligence on an address. Pass coordinates and the country_code from geocode_address: France has the full 36-category report; Germany a partial report from open German data. An out-of-coverage point returns an empty report rather than an error.

Параметры

Параметр	Тип	Описание	Обязательный
`lat`	`number`	Latitude (WGS84). Obtain it from geocode_address.	Да
`lng`	`number`	Longitude (WGS84). Obtain it from geocode_address.	Да
`country`	`string`	ISO 3166-1 alpha-2 country code from geocode_address (country_code): fr for the full report, de for the German partial report. Defaults to fr.	Нет
`lang`	`string`	Response language: en, de, fr, it, ru or es. Defaults to en.	Нет

Возвращает

Поле	Тип	Описание
`latitude`	`number`	Latitude (WGS84).
`longitude`	`number`	Longitude (WGS84).
`risk_score`	`integer`	Overall risk score (0-100); null if out of coverage.
`risk_label`	`string`	Label for the risk score.
`total_insights`	`integer`	Number of insights returned.
`insights`	`array`	Categorised buyer insights.
`category`	`string`	Insight category.
`severity`	`string`	Severity level.
`title`	`string`	Short title.
`detail`	`string`	What was found.
`recommendation`	`string`	Suggested action.
`regulation`	`string`	Applicable regulation, if any.
`source`	`string`	Knowledge-graph inference chain that produced this insight.
`confidence`	`number`	Data reliability (0-1), from the source quality tier.
`source_version`	`string`	Data source identifier, e.g. bdnb_open_data or the German source.

get_renovation_advice

Prioritised renovation and energy plan for a building: the renovation-relevant findings — envelope insulation deficiencies, heating and hot-water obsolescence, the worst heat-loss element, window quality, thermal bridges, the estimated energy bill, carbon footprint, the DPE rental-ban regulation, and green-energy / district-heating options — filtered from the full building report and ordered most-urgent first with a priority rank, so you can advise what to fix first. France has the full analysis; Germany a partial one. Pass coordinates and the country_code from geocode_address. Out of coverage returns an empty plan, not an error.

Параметры

Параметр	Тип	Описание	Обязательный
`lat`	`number`	Latitude (WGS84). Obtain it from geocode_address.	Да
`lng`	`number`	Longitude (WGS84). Obtain it from geocode_address.	Да
`country`	`string`	ISO 3166-1 alpha-2 country code from geocode_address (country_code): fr for the full report, de for the German partial report. Defaults to fr.	Нет
`lang`	`string`	Response language: en, de, fr, it, ru or es. Defaults to en.	Нет

Возвращает

Поле	Тип	Описание
`latitude`	`number`	Latitude (WGS84).
`longitude`	`number`	Longitude (WGS84).
`total_steps`	`integer`	Number of renovation steps returned.
`steps`	`array`	Renovation-relevant insights, most urgent first (fix the first one first).
`category`	`string`	Insight category.
`severity`	`string`	Severity level.
`title`	`string`	Short title.
`detail`	`string`	What was found.
`recommendation`	`string`	Suggested action.
`regulation`	`string`	Applicable regulation, if any.
`source`	`string`	Knowledge-graph inference chain that produced this insight.
`confidence`	`number`	Data reliability (0-1), from the source quality tier.
`source_version`	`string`	Data source identifier, e.g. bdnb_open_data.

get_property_report

One-shot due-diligence report for an address: bundles the building insights (energy/DPE, structural, regulatory and natural/technological risks), comparable sold properties, price-per-square-metre trends, the location rating (mean price and net rent), the risk assessment, the local environment (air quality, seasonal climate, neighbourhood and noise) and the commune's short-term-rental regime into a single response. Use for a complete property review in one call instead of chaining the individual tools; each section matches its dedicated tool's shape. Any section out of coverage is omitted. France is covered in depth; elsewhere the sections that resolve are returned. Pass coordinates and the country_code from geocode_address.

Параметры

Параметр	Тип	Описание	Обязательный
`lat`	`number`	Latitude (WGS84). Obtain it from geocode_address.	Да
`lng`	`number`	Longitude (WGS84). Obtain it from geocode_address.	Да
`country`	`string`	ISO 3166-1 alpha-2 country code from geocode_address (country_code): fr for the full report, de for the German partial report. Defaults to fr.	Нет
`lang`	`string`	Response language: en, de, fr, it, ru or es. Defaults to en.	Нет

Возвращает

Поле	Тип	Описание
`latitude`	`number`	Latitude (WGS84).
`longitude`	`number`	Longitude (WGS84).
`building_insights`	`object`	Same shape as get_building_insights. Null if out of coverage.
`comparable_sales`	`object`	Same shape as get_comparable_sales. Null if unavailable.
`price_trends`	`object`	Same shape as get_price_trends. Null if unavailable.
`location_rating`	`object`	Same shape as get_location_rating. Null if unavailable.
`risk_assessment`	`object`	Same shape as get_risk_assessment. Null if unavailable.
`air_quality`	`object`	Same shape as get_air_quality. Null if unavailable.
`seasonal_climate`	`object`	Same shape as get_seasonal_climate. Null if unavailable.
`neighborhood`	`object`	Same shape as get_neighborhood. Null if unavailable.
`noise`	`object`	Same shape as get_noise. Null if unavailable.
`short_term_rental`	`object`	Same shape as get_short_term_rental. Null outside France.

get_risk_assessment

Natural and technological risk assessment for a location (official GeoRisques data): flood, seismic, clay/subsidence and radon. France only. Pass coordinates from geocode_address.

Параметры

Параметр	Тип	Описание	Обязательный
`lat`	`number`	Latitude (WGS84). Obtain it from geocode_address.	Да
`lng`	`number`	Longitude (WGS84). Obtain it from geocode_address.	Да
`lang`	`string`	Response language: en, de, fr, it, ru or es. Defaults to en.	Нет

Возвращает

Поле	Тип	Описание
`risks`	`array`	One entry per hazard.
`category`	`string`	Hazard, e.g. flood, seismic, clay, radon.
`grade`	`string`	Risk grade.
`explanation`	`string`	What the grade means here.
`confidence`	`number`	Confidence (0-1).

get_short_term_rental

Short-term-rental (Airbnb) regime of the commune a location lies in, for a home the owner does not live in: whether a changement d'usage permit is needed, whether the commune is closed to new lets (quota reached or compensation required), the yearly day cap for the owner's own home, the règlement's specifics and its source. Derived from the national registration list and each commune's own règlement; an absent status means no local rule is on file, not that letting is allowed. France only. Pass coordinates from geocode_address.

Параметры

Параметр	Тип	Описание	Обязательный
`lat`	`number`	Latitude (WGS84). Obtain it from geocode_address.	Да
`lng`	`number`	Longitude (WGS84). Obtain it from geocode_address.	Да
`lang`	`string`	Response language: en, de, fr, it, ru or es. Defaults to en.	Нет

Возвращает

Поле	Тип	Описание
`insee`	`string`	INSEE code of the commune.
`commune`	`string`	Commune name.
`status`	`string`	Regime for a home the owner does not live in: OPEN (verified: no local rule), AUTHORIZATION (changement d'usage permit needed), CAPPED (closed to new lets: quota reached or compensation from the first square metre), UNDER_REVIEW (restriction being debated). Absent when no local rule is on file — not known, not a guarantee.
`compensation`	`boolean`	A replacement dwelling is required at least in part of the commune.
`quota`	`boolean`	The number of permits is limited.
`quota_full`	`boolean`	That limit is known to be reached.
`primary_days`	`integer`	Days per year the owner's own main home may be let: 120 by law, 90 where the council lowered it.
`note`	`string`	The règlement's specifics in the requested language.
`source_url`	`string`	Mairie / EPCI page or open-data list the row is based on.
`verified_at`	`string`	Date the row was last checked against its source (ISO 8601).

MCP

Начать

Запроси доступ разработчика, создай API-ключ и подключи свой MCP-клиент.

Получить API-ключ Подключение

Справочник API

Подключение

Соглашения

Инструменты

Поиск и данные

Рынок

Локация и окружение

Insights

Начать

Secrets.RealEstate

Продукт

Инфо

Аккаунт