# Idealista MCP tools

> Every Idealista MCP tool on the Cotlet server: tool names, input schemas, a tools/call example and an example result for each tool.

Source: https://cotlet.dev/docs/mcp/idealista

Docs sections: [Get started](https://cotlet.dev/docs.md) · [REST API](https://cotlet.dev/docs/api.md) · [MCP](https://cotlet.dev/docs/mcp.md) · [SDKs & CLI](https://cotlet.dev/docs/sdks.md) · [Integrations](https://cotlet.dev/docs/integrations.md)

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: https://cotlet.dev/integrations/idealista-api-mcp-server

## 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

MCP tool: `idealista_list_listings`

Access: read.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `status` | enum | no | active, inactive or all. Default: active. |
| `operation` | enum | no | sale, rent or all. Default: all. |
| `limit` | integer | no | 1 to 100. Default: 50. |
| `cursor` | string | no | Next page cursor from the previous call. |

### tools/call

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

### Example response

```json
{
  "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

MCP tool: `idealista_get_listing`

Access: read.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `listing_id` | string | yes | Listing ID from list_listings. |

### tools/call

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

### Example response

```json
{
  "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

MCP tool: `idealista_get_listing_stats`

Access: read.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `listing_id` | string | yes | Listing ID from list_listings. |
| `period` | enum | no | 7d, 30d or 90d. Default: 30d. |

### tools/call

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

### Example response

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

## List contacts

MCP tool: `idealista_list_contacts`

Access: read.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `listing_id` | string | no | Only contacts about this listing. |
| `state` | enum | no | active, unread, handled or archived. Default: active. |
| `since` | date | no | Only contacts with messages on or after this date. |
| `cursor` | string | no | Next page cursor from the previous call. |

### tools/call

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

### Example response

```json
{
  "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

MCP tool: `idealista_get_conversation`

Access: read.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `contact_id` | string | yes | Contact ID from list_contacts. |

### tools/call

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

### Example response

```json
{
  "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

MCP tool: `idealista_list_demands`

Access: read.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `operation` | enum | no | sale, rent or all. Default: all. |
| `limit` | integer | no | 1 to 100. Default: 50. |

### tools/call

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

### Example response

```json
{
  "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

MCP tool: `idealista_update_listing`

Access: write. Confirm: waits for the user's OK before it runs.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `listing_id` | string | yes | Listing ID from list_listings. |
| `fields` | object | yes | Any of price, description, size_m2, rooms, bathrooms, features. |

### tools/call

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

### Example response

```json
{
  "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

MCP tool: `idealista_deactivate_listing`

Access: write.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `listing_id` | string | yes | Listing ID from list_listings. |

### tools/call

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

### Example response

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

## Reactivate listing

MCP tool: `idealista_reactivate_listing`

Access: write. Confirm: waits for the user's OK before it runs.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `listing_id` | string | yes | Listing ID from list_listings. |

### tools/call

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

### Example response

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

## Reply to contact

MCP tool: `idealista_reply_to_contact`

Access: write. Confirm: waits for the user's OK before it runs.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `contact_id` | string | yes | Contact ID from list_contacts. |
| `body` | string | yes | Message text. |

### tools/call

```json
{
  "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

```json
{
  "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

MCP tool: `idealista_send_listings_to_contact`

Access: write. Confirm: waits for the user's OK before it runs.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `contact_id` | string | yes | Contact ID from list_contacts. |
| `listing_ids` | string[] | yes | Up to 5 listing IDs from list_listings. |
| `body` | string | no | Message sent with the properties. |

### tools/call

```json
{
  "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

```json
{
  "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

MCP tool: `idealista_mark_contact_handled`

Access: write.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `contact_id` | string | yes | Contact ID from list_contacts. |

### tools/call

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

### Example response

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

## Add contact note

MCP tool: `idealista_add_contact_note`

Access: write.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `contact_id` | string | yes | Contact ID from list_contacts. |
| `note` | string | yes | Note text. |

### tools/call

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

### Example response

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

## Archive conversation

MCP tool: `idealista_archive_conversation`

Access: write.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `contact_id` | string | yes | Contact ID from list_contacts. |

### tools/call

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

### Example response

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