MCP tools reference

Idealista MCP tools

14 tools for Idealista on the Cotlet MCP server. Your agent picks them from tools/list.

MCP server
https://cotlet.dev/mcp/v1
Connects with
Your Idealista account, as a private advertiser or an idealista/tools agency user
Integration page
Idealista
Idealista Endpoints
Endpoint Access Description
idealista_list_listings read Your ads with status, operation, price, address and quality score.
idealista_get_listing read Full ad: price, size, rooms, features, description, photos count, URL and quality score.
idealista_get_listing_stats read Visits, contacts and favorites of a listing for a period.
idealista_list_contacts read People who contacted you in Inbox, with the listing, last message and unread count.
idealista_get_conversation read All messages with one contact, with dates, notes and the listing they asked about.
idealista_list_demands read Demands created from your contacts in idealista/tools, with what each person is looking for.
idealista_update_listing write Change the price, description or features of one of your ads.
idealista_deactivate_listing write Take an ad off search results. It stays in your account and can be reactivated.
idealista_reactivate_listing write Put an expired or deactivated ad back in search results.
idealista_reply_to_contact write Send a chat message as you to a contact in Inbox.
idealista_send_listings_to_contact write Share other properties from your portfolio in the conversation.
idealista_mark_contact_handled write Mark a contact as handled, for example after a phone call.
idealista_add_contact_note write Private note on a conversation, only visible to you and your team.
idealista_archive_conversation write Move a finished conversation out of the active list.

List listings

read

MCP tool idealista_list_listings

Lists the ads in your account, newest first. Use the listing_id of each item in the other tools. Filter by status to see deactivated ads and by operation to separate sales from rentals. Pages hold up to 100 ads; pass next_cursor back as cursor for the next page.

Parameters

Parameters: list_listings
NameTypeDescription
status enum active, inactive or all. Default: active.
operation enum sale, rent or all. Default: all.
limit integer 1 to 100. Default: 50.
cursor string Next page cursor from the previous call.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "idealista_list_listings",
    "arguments": {}
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "listings": [
      {
        "listing_id": "108274561",
        "title": "Flat in Malasana, Madrid",
        "operation": "rent",
        "status": "active",
        "price": 1450,
        "currency": "EUR",
        "quality_score": 82,
        "url": "https://www.idealista.com/inmueble/108274561/"
      }
    ],
    "next_cursor": null
  },
  "isError": false
}

Get listing

read

MCP tool idealista_get_listing

Returns one ad as it appears on Idealista, with its description, features and number of photos. Use it before update_listing to see the current values, and after it to confirm the change.

Parameters

Parameters: get_listing
NameTypeDescription
listing_id required string Listing ID from list_listings.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "idealista_get_listing",
    "arguments": {
      "listing_id": "listing_8c41d2"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "listing_id": "108274561",
    "operation": "rent",
    "status": "active",
    "price": 1450,
    "currency": "EUR",
    "size_m2": 68,
    "rooms": 2,
    "bathrooms": 1,
    "features": [
      "lift",
      "air conditioning"
    ],
    "description": "Bright two-bedroom flat near Calle Fuencarral.",
    "photos": 14,
    "quality_score": 82,
    "url": "https://www.idealista.com/inmueble/108274561/"
  },
  "isError": false
}

Get listing stats

read

MCP tool idealista_get_listing_stats

Returns the number of visits, contacts and favorites an ad received in the period, as the statistics of your account show them. One listing per call.

Parameters

Parameters: get_listing_stats
NameTypeDescription
listing_id required string Listing ID from list_listings.
period enum 7d, 30d or 90d. Default: 30d.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "idealista_get_listing_stats",
    "arguments": {
      "listing_id": "108274561",
      "period": "30d"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "listing_id": "108274561",
    "period": "30d",
    "visits": 912,
    "contacts": 14,
    "favorites": 37
  },
  "isError": false
}

List contacts

read

MCP tool idealista_list_contacts

Lists contacts in your Inbox, most recent first, each with the listing it is about, the last message and the number of unread messages. State matches the Inbox lists: active, unread, handled or archived. Pages hold up to 50 contacts; pass next_cursor back as cursor.

Parameters

Parameters: list_contacts
NameTypeDescription
listing_id string Only contacts about this listing.
state enum active, unread, handled or archived. Default: active.
since date Only contacts with messages on or after this date.
cursor string Next page cursor from the previous call.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "idealista_list_contacts",
    "arguments": {}
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "contacts": [
      {
        "contact_id": "c_83920417",
        "name": "Marta R.",
        "listing_id": "108274561",
        "state": "unread",
        "unread": 1,
        "last_message": "Is it still available?",
        "updated_at": "2026-10-10T17:55:00+02:00"
      }
    ],
    "next_cursor": null
  },
  "isError": false
}

Get conversation

read

MCP tool idealista_get_conversation

Returns the messages of one conversation, oldest first, with your private notes and the listing the contact asked about. Your agent should read it before replying.

Parameters

Parameters: get_conversation
NameTypeDescription
contact_id required string Contact ID from list_contacts.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "idealista_get_conversation",
    "arguments": {
      "contact_id": "contact_8c41d2"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "contact_id": "c_83920417",
    "listing_id": "108274561",
    "messages": [
      {
        "from": "contact",
        "body": "Is it still available?",
        "sent_at": "2026-10-10T17:55:00+02:00"
      }
    ],
    "notes": []
  },
  "isError": false
}

List demands

read

MCP tool idealista_list_demands

Lists the demands you created from contacts in idealista/tools, each with the operation, area and budget the person is looking for. Use it to match new listings to people already waiting. Agency accounts in idealista/tools only.

Parameters

Parameters: list_demands
NameTypeDescription
operation enum sale, rent or all. Default: all.
limit integer 1 to 100. Default: 50.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "idealista_list_demands",
    "arguments": {}
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "demands": [
      {
        "demand_id": "d_2210",
        "contact_id": "c_83920417",
        "operation": "rent",
        "area": "Malasana",
        "max_price": 1600,
        "currency": "EUR",
        "rooms": 2
      }
    ]
  },
  "isError": false
}

Update listing

write Confirm

MCP tool idealista_update_listing

Changes the fields you pass and leaves the rest as they are. The new price and text are public once saved. Returns the ad as saved, so your agent can check it. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: update_listing
NameTypeDescription
listing_id required string Listing ID from list_listings.
fields required object Any of price, description, size_m2, rooms, bathrooms, features.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "idealista_update_listing",
    "arguments": {
      "listing_id": "108274575",
      "fields": {
        "price": 245000
      }
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "listing_id": "108274561",
    "status": "active",
    "price": 245000,
    "currency": "EUR",
    "updated_at": "2026-10-10T18:20:00+02:00"
  },
  "isError": false
}

Deactivate listing

write

MCP tool idealista_deactivate_listing

Deactivates one ad, so it no longer shows in search results. The ad stays in your account. deactivate_listing runs without asking first: it messages no one and reactivate_listing undoes it.

Parameters

Parameters: deactivate_listing
NameTypeDescription
listing_id required string Listing ID from list_listings.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "idealista_deactivate_listing",
    "arguments": {
      "listing_id": "108274590"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "listing_id": "108274561",
    "status": "inactive"
  },
  "isError": false
}

Reactivate listing

write Confirm

MCP tool idealista_reactivate_listing

Reactivates one ad that expired or was deactivated, so it shows in search results again. An ad cannot be reactivated if the account was closed together with it. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: reactivate_listing
NameTypeDescription
listing_id required string Listing ID from list_listings.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "idealista_reactivate_listing",
    "arguments": {
      "listing_id": "listing_8c41d2"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "listing_id": "108274561",
    "status": "active"
  },
  "isError": false
}

Reply to contact

write Confirm

MCP tool idealista_reply_to_contact

Sends a message in the Inbox conversation with one contact, under your name. It appears next to the messages you wrote by hand. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: reply_to_contact
NameTypeDescription
contact_id required string Contact ID from list_contacts.
body required string Message text.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "idealista_reply_to_contact",
    "arguments": {
      "contact_id": "c_83920417",
      "body": "Hi, the flat is still available. I can show it on Saturday at 11:00 or 12:30."
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "contact_id": "c_83920417",
    "message_id": "m_552019384",
    "status": "sent",
    "sent_at": "2026-10-10T18:42:00+02:00"
  },
  "isError": false
}

Send listings to contact

write Confirm

MCP tool idealista_send_listings_to_contact

Attaches up to 5 of your listings to the conversation with one contact, with an optional message, like the clip icon in Inbox. The contact sees them under your name. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: send_listings_to_contact
NameTypeDescription
contact_id required string Contact ID from list_contacts.
listing_ids required string[] Up to 5 listing IDs from list_listings.
body string Message sent with the properties.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "idealista_send_listings_to_contact",
    "arguments": {
      "contact_id": "contact_8c41d2",
      "listing_ids": [
        "listing ids"
      ]
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "contact_id": "c_83920417",
    "message_id": "m_552019390",
    "listing_ids": [
      "108274562",
      "108274563"
    ],
    "status": "sent"
  },
  "isError": false
}

Mark contact as handled

write

MCP tool idealista_mark_contact_handled

Marks one contact as handled, the green check in Inbox, for example after you dealt with it by phone. It messages no one and is undone from Inbox. mark_contact_handled runs without asking first.

Parameters

Parameters: mark_contact_handled
NameTypeDescription
contact_id required string Contact ID from list_contacts.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "idealista_mark_contact_handled",
    "arguments": {
      "contact_id": "contact_8c41d2"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "contact_id": "c_83920417",
    "state": "handled"
  },
  "isError": false
}

Add contact note

write

MCP tool idealista_add_contact_note

Adds a note to the conversation detail. The contact never sees it. add_contact_note runs without asking first, because it reaches no one.

Parameters

Parameters: add_contact_note
NameTypeDescription
contact_id required string Contact ID from list_contacts.
note required string Note text.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "idealista_add_contact_note",
    "arguments": {
      "contact_id": "contact_8c41d2",
      "note": "note"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "contact_id": "c_83920417",
    "note_id": "n_4410",
    "status": "saved"
  },
  "isError": false
}

Archive conversation

write

MCP tool idealista_archive_conversation

Archives one conversation, so it leaves the active list. Idealista lets you reactivate an archived request from the conversation, so nothing is lost. archive_conversation runs without asking first: it messages no one.

Parameters

Parameters: archive_conversation
NameTypeDescription
contact_id required string Contact ID from list_contacts.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "idealista_archive_conversation",
    "arguments": {
      "contact_id": "contact_8c41d2"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "contact_id": "c_83920417",
    "state": "archived"
  },
  "isError": false
}