<img width="28" height="28" alt="download" src="https://github.com/user-attachments/assets/78809272-e450-4ff3-9f59-573617537f06" />

# idealista-mcp

MCP server for Idealista messaging. Connects to a Chrome instance you run yourself via Chrome DevTools Protocol (CDP). No browser is launched automatically.

## Requirements

- Node.js >= 20
- Google Chrome (or Chromium) installed
- An Idealista account, already logged in inside the Chrome profile you launch

## Start Chrome with remote debugging

You must close any existing Chrome instance before running these commands — if Chrome is already open, the debugging port will not be exposed.

**macOS**
```bash
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.config/chrome-idealista"
```

**Linux**
```bash
google-chrome \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.config/chrome-idealista"
```

**Windows (PowerShell)**
```powershell
& "C:\Program Files\Google\Chrome\Application\chrome.exe" `
  --remote-debugging-port=9222 `
  --user-data-dir="$env:USERPROFILE\chrome-idealista"
```

Use a dedicated `--user-data-dir` so this profile is separate from your everyday Chrome. Log into Idealista inside this instance; the server reuses those cookies.

## Install

This package is not published to npm. Install from source:

```bash
git clone https://github.com/0p3rador/ide4lista-mcp
cd ide4lista-mcp
npm install
npm run build
npm link
```

## MCP client configuration

**Option A — installed via `npm link` (recommended for development)**

```json
{
  "mcpServers": {
    "idealista": {
      "command": "ide4lista-mcp",
      "env": {
        "IDEALISTA_CDP_ENDPOINT": "http://localhost:9222"
      }
    }
  }
}
```

**Option B — absolute path to the built file**

```json
{
  "mcpServers": {
    "idealista": {
      "command": "node",
      "args": ["/absolute/path/to/idealista-mcp/dist/index.js"],
      "env": {
        "IDEALISTA_CDP_ENDPOINT": "http://localhost:9222"
      }
    }
  }
}
```

Replace `/absolute/path/to/idealista-mcp` with the directory where you cloned the repo.

## Environment variables

| Variable | Default | Description |
|---|---|---|
| `IDEALISTA_CDP_ENDPOINT` | `http://localhost:9222` | Chrome DevTools Protocol endpoint |
| `IDEALISTA_ORIGIN` | `https://www.idealista.com` | Idealista domain (`.com`, `.it`, `.pt`). Must be a valid `https:` URL. |
| `IDEALISTA_DRAFT_TTL_MS` | `300000` | Draft expiry in ms (5 min). Must be positive. |
| `IDEALISTA_PAGE_PAUSE_MS` | `1500` | Pause between paginated list requests in ms. Must be positive. |
| `IDEALISTA_CAPTURE_LIMIT` | `300` | Max XHR entries buffered by `capture_start`. Must be positive. |

## Tools

| Tool | Effect | Notes |
|---|---|---|
| `check_session` | Read — checks authentication status | Uses `/menu-api`, validates `me.name` |
| `get_counters` | Read — unread count + starred conversations | Lightweight alternative to listing |
| `list_conversations` | Read — first page of inbox | Returns `hasPrevious`/`hasNext` |
| `list_pending` | Read — conversations awaiting your reply | Paginates full inbox; respects `max_age_days` and `limit` |
| `get_conversation` | Read — recent messages, descending | Fetches N messages newest-first |
| `draft_message` | Read — creates an in-memory draft | Returns draft_id + last message for review |
| `send_message` | **WRITE — sends a message** | Requires `confirmed: true` and `recipient_name` matching the draft |
| `capture_start` | Read — begins XHR capture | Pass `include_body: true` for full response bodies |
| `capture_stop` | Read — returns captured requests | Stops capture; error if none was active |

### Sending a message: required flow

```
draft_message(conversation_id, text)
  → returns { draft_id, recipient_name, last_message, ... }

Review the draft and last_message carefully.

send_message(draft_id, confirmed: true, recipient_name: "<exact name from draft>")
  → returns { sent: true, messageId, conversationId }
```

`send_message` is the **only tool that writes data**. It requires `confirmed: true` and a `recipient_name` that matches the draft exactly — this guards against sending to the wrong person. Drafts expire after `IDEALISTA_DRAFT_TTL_MS` ms.

If `send_message` returns a network error, the message **may or may not have been delivered**. Do not retry automatically — check `get_conversation` first. If the draft is marked ambiguous, create a new one with `draft_message` only after confirming the original did not arrive.

## Security notes

**`capture_start` with `include_body: true`** dumps third-party personal data (names, phone numbers, message content) into the model context. Do not share, log, or republish this output.

External message content is wrapped in `<mensaje_externo_NONCE>` tags. The nonce changes per call and the closing tag is escaped out of the content, which reduces the risk of injected text breaking out of the delimited block. This is a partial mitigation, not a guarantee.

## Limits and terms of service

This tool automates access to your own Idealista account. Automated access may conflict with Idealista's terms of service. Use it at a human pace, for your own account only.

`mark-as-read` is **not implemented deliberately**. Whether `GET /messages` triggers server-side read marking is unverified — do not assume this server leaves conversations unread.