Idealista MCP Server

Connect an AI assistant to Idealista listings in Spain, Italy and Portugal. This Model Context Protocol (MCP) server gives Claude, Cursor, n8n or your own agent four tools: search listings by place and filters, autocomplete locations, read one listing in full, and list an agency's listings from its phone number. The same Actor also runs as a normal one-shot scraper that writes to a dataset.

It uses Idealista's Android app API. No login is needed and no proxy was needed in our tests. Each call queries Idealista when it is made.

Tools

Tool	What it returns
search_idealista_properties(location, country, operation, property_type, limit, min_price, max_price, min_size, max_size, min_rooms, min_bathrooms, sort_by)	Up to 200 listings per call for a city, area or neighborhood (name resolved automatically): price, size, rooms, bathrooms, address, municipality, GPS, labels, thumbnail, a description excerpt and the advertiser (agency name and phone for professional sellers only).
search_idealista_locations(prefix, country, property_type, operation, limit)	Matching locations with Idealista's locationId / zoiId, name and type, to check how a place name resolves.
get_idealista_property_detail(property_code, country, language)	The full record of one listing: features, energy certificate, full description, photo URLs, GPS, agency contact, last-modified date.
search_idealista_by_phone(phone, country, operation, property_type, limit)	The listings of the agency behind a phone number, in the same compact format as the search.

country is es, it or pt; operation is sale or rent; property_type is homes, newDevelopments, offices, premises, garages, lands, storageRooms, buildings or bedrooms. A call that fails or finds nothing returns an error field (or an empty list) and is not charged.

Example prompts: "Find 20 flats for sale in Chamberi under 600,000 EUR with at least 2 bedrooms", "Show the full record of Idealista listing 106534215", "List every listing of the agency with phone 865440400".

Connect it

Start the Actor in Standby mode. The server listens at

https://<your-username>--idealista-mcp-scraper.apify.actor/mcp

Send your Apify API token as Authorization: Bearer <token>. In an MCP client that supports Streamable HTTP servers:

{
    "mcpServers": {
        "idealista": {
            "url": "https://<your-username>--idealista-mcp-scraper.apify.actor/mcp",
            "headers": { "Authorization": "Bearer <your Apify token>" }
        }
    }
}

Classic run (no AI needed)

Press Start with a location (or an agent phone) and the Actor pages through the results and writes one row per listing to the dataset. With neither set, the run ends immediately with a note (the MCP server only runs in Standby mode).

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

Input	Default	Description
country	es	es, it or pt
location / phone	empty	Place name, or an agent phone number
operation, propertyType	sale, homes	Listing type
minPrice, maxPrice, minSize, maxSize, minRooms, minBathrooms	none	Filters
sortBy, sinceDate	relevance, any time	Ordering and publication-date window
limit	60	Max listings (up to 5000; one search slice pages about 60 pages, so split large cities by price)
fetchFullDetails	off	Replace each row by the full listing record (one extra request per listing, slower)

Output fields include propertyCode, url, title, operation, propertyType, price, currency, sizeM2, rooms, bathrooms, floor, address, municipality, province, latitude, longitude, description, agencyName, agencyPhone, sellerType, thumbnail, images and more. Fields Idealista does not provide are null.

Use cases

• Give a real-estate assistant live listings and prices for a neighborhood.
• Research which agencies list in an area (agency name and phone come with professional listings).
• Monitor price drops: schedule a classic run and compare price and priceDropValue over time.

FAQ

Which countries work? Spain, Italy and Portugal.

Do I need a proxy? No proxy was needed in our tests. Idealista's edge sometimes soft-blocks an address for a few minutes; the Actor retries, and if it still fails the tool returns an error and you are not charged.

How many listings per search? Up to 200 per tool call. Idealista pages about 60 pages (roughly 1,800 listings) per query slice, so split very large cities by price range.

Are private sellers' phone numbers included? No. Agency name and phone are output only for professional sellers; for private sellers those fields are null.

Is this affiliated with Idealista? No. It is an independent tool; you are responsible for complying with Idealista's terms and applicable law.