Idealista MCP Scraper

Query Idealista — Spain, Italy and Portugal's biggest real-estate marketplace — live from your AI agent. This Actor is a Model Context Protocol (MCP) server: connect Claude, ChatGPT, Cursor, n8n or any MCP client and search properties, resolve locations, pull full property details and find agents by phone in real time. It also runs as a classic one-shot scraper when you just want a dataset.

Built on Idealista's official Android mobile API with HMAC request signing — no proxy required, no datacenter blocks.

---

Why use this Actor

• MCP-native — your AI agent calls Idealista directly, no glue code.
• 3 countries — Spain (es), Italy (it), Portugal (pt).
• Official mobile API — reliable, fast, structured JSON (no fragile HTML parsing).
• Powerful filters — price, size, bedrooms, bathrooms, operation, property type, recency.
• Agent lookup — find every listing published by a phone number.
• Dual mode — live MCP server or classic scraper to a dataset.

---

MCP tools

Tool	What it does
search_idealista_properties	Search listings by location name (auto-resolved) with full filters.
search_idealista_locations	Autocomplete locations → returns official locationId / zoiId.
get_idealista_property_detail	Full detail for one property by propertyCode (description, photos, features).
search_idealista_by_phone	Find all listings published by an agent's phone number.

Example agent prompts

"Find 20 flats for sale in Chamberí, Madrid under €600,000 with at least 2 bedrooms."

"Resolve the location ID for 'primera línea de playa de Málaga'."

"Get the full details for Idealista property 106534215."

"List every property listed by agent phone 865440400."

---

Connecting an MCP client

Start the Actor in Standby mode, then point your MCP client at the Streamable HTTP endpoint:

https://<your-actor-standby-url>/mcp

Claude Desktop / Cursor (mcp.json):

{
    "mcpServers": {
        "idealista": {
            "url": "https://<your-actor-standby-url>/mcp",
            "headers": { "Authorization": "Bearer <YOUR_APIFY_TOKEN>" }
        }
    }
}

---

Classic scraper mode

Prefer a plain dataset? Run the Actor normally with an input. Provide a location (or a phone) and the Actor paginates and pushes normalized rows to the dataset.

Example input

{
    "country": "es",
    "location": "Madrid",
    "operation": "sale",
    "propertyType": "homes",
    "minPrice": 100000,
    "maxPrice": 500000,
    "minRooms": 2,
    "sortBy": "price",
    "limit": 60,
    "fetchFullDetails": false
}

Input parameters

Field	Type	Description
country	string	es, it or pt. Default es.
location	string	City / area / neighborhood name (auto-resolved).
phone	string	Optional — scrape all listings by an agent phone number.
operation	string	sale or rent.
propertyType	string	homes, newDevelopments, offices, premises, garages, lands, storageRooms, buildings, bedrooms.
limit	integer	Max properties to return. Default 60.
minPrice / maxPrice	integer	Price range in euros.
minSize / maxSize	integer	Size range in m².
minRooms	integer	Minimum bedrooms.
minBathrooms	integer	Minimum bathrooms.
sortBy	string	weigh (relevance), price, publicationDate, size.
sinceDate	string	-1 (any), T (24h), Y (48h), W (week), M (month).
fetchFullDetails	boolean	Also fetch full description, images and features per property.

---

Output fields

Each dataset row is a normalized property:

Field	Description
propertyCode	Idealista property ID.
url	Listing URL.
price	Price in euros.
size	Size in m².
rooms / bathrooms	Bedroom / bathroom counts.
address / municipality / province	Location.
latitude / longitude	GPS coordinates.
thumbnail	Main image.
operation / propertyType	Listing classification.
country	Market (es / it / pt).
description / images / features	Included when fetchFullDetails is enabled.

---

Pricing

This Actor uses Pay Per Event: a flat fee per MCP tool call (and per classic run that performs the same work). You only pay for what your agent actually queries.

---

Use cases

• Real-estate market research — track prices and inventory by area.
• Lead generation — find listings and the agents behind them.
• Price monitoring — schedule runs and watch a neighborhood over time.
• AI assistants — give your agent live property search super-powers.

---

Scheduling & integration

Run it on a schedule, trigger via the Apify API, or wire dataset webhooks into your CRM / data warehouse. In MCP mode, keep it in Standby and let your agents query on demand.

---

FAQ

Do I need a proxy? No. The official mobile API works directly.

Which countries are supported? Spain, Italy and Portugal.

Can I use it without an AI agent? Yes — run it as a classic scraper with a location input.

Is this affiliated with Idealista? No. This is an independent tool that uses Idealista's public mobile API.