# Leboncoin MCP Server (`axlymxp/leboncoin-mcp-scraper`) Actor

MCP server for leboncoin.fr: let Claude, Cursor, ChatGPT or n8n search classifieds, open listings, find similar ads and a seller's other ads live over MCP. Real estate, cars and more via the mobile API. Also runs as a one-shot scraper with a dataset.

- **URL**: https://apify.com/axlymxp/leboncoin-mcp-scraper.md
- **Developed by:** [axly](https://apify.com/axlymxp) (community)
- **Categories:** AI, Real estate, E-commerce
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 dataset items

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Leboncoin MCP Server

Give your AI assistant live access to leboncoin.fr, France's largest classifieds marketplace. This Actor runs as a
**Model Context Protocol (MCP) server**, so Claude, Cursor, ChatGPT, n8n and other MCP clients can search listings,
open a listing in full, find similar ads and list a seller's other ads in real time. It also runs as a **classic
scraper** when you just want a dataset.

It reads the leboncoin mobile API (no account or login needed) through Apify RESIDENTIAL proxies in France, and
handles leboncoin's anti-bot checks for you by switching to a new proxy exit when one is challenged.

### MCP tools

| Tool               | What it does                                                                                                   |
| ------------------ | -------------------------------------------------------------------------------------------------------------- |
| `search_listings`  | Search any category with filters (location, price, surface, rooms, seller type, sort) and get normalized rows  |
| `get_listing`      | Full detail for one listing id: complete description, all images, seller, location, attributes                 |
| `similar_listings` | Ads similar to a given listing                                                                                 |
| `ads_by_seller`    | Other active ads from the same seller                                                                          |
| `search_around_me` | Latest listings within a radius around a lat/lng point                                                         |

Search-style tools return up to 100 listings per call (default 20), with a 400-character description preview and the
first 3 image URLs per listing to keep responses compact. Use `get_listing` for the full text and every image.
Sponsored ads are excluded, so price sorting is exact.

A tool call that fails (for example because leboncoin kept challenging every proxy exit) or returns no data is not
charged.

### Output fields (per listing)

| Field                                                                                     | Description                          |
| ----------------------------------------------------------------------------------------- | ------------------------------------ |
| `list_id`, `url`, `subject`, `body`                                                       | Identity, title, description         |
| `category_id`, `category_name`, `ad_type`, `status`                                       | Category and state                   |
| `first_publication_date`, `index_date`                                                    | Publication timestamps               |
| `price`, `price_cents`, `currency`                                                        | Price in euros                       |
| `owner_name`, `owner_type`, `owner_store_id`, `owner_user_id`, `owner_siren`              | Seller                               |
| `city`, `zipcode`, `district`, `department_id/name`, `region_id/name`, `lat`, `lng`       | Location                             |
| `real_estate_type`, `square`, `rooms`, `bedrooms`, `energy_rate`, `ges`, `furnished`      | Real-estate attributes               |
| `nb_images`, `thumbnail`, `images`, `has_phone`                                           | Media and contact flag               |
| `attributes`, `attribute_labels`                                                          | Every attribute of the ad (key/value) |

Attributes differ by category (cars have brand, model, mileage, fuel...), so the `attributes` map is the place to
look for category-specific fields.

### Connect it

1. Open the Actor in the Apify Console and enable **Standby** (or call its Standby URL directly).
2. Point your MCP client at `https://<your-actor-standby-url>/mcp` (Streamable HTTP) with your Apify token as a
   bearer token.
3. The five tools appear in your assistant.

Example MCP client config:

```json
{
    "mcpServers": {
        "leboncoin": {
            "url": "https://<your-actor-standby-url>/mcp",
            "headers": { "Authorization": "Bearer <APIFY_TOKEN>" }
        }
    }
}
```

### Classic run (dataset)

Prefer a plain dataset? Run the Actor normally with an input like:

```json
{
    "category": "9",
    "departmentIds": ["75"],
    "priceMax": 600000,
    "roomsMin": 2,
    "sortBy": "time",
    "sortOrder": "desc",
    "maxItems": 20,
    "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"], "apifyProxyCountry": "FR" }
}
```

It pushes the same normalized listing rows as the search tool to the dataset. Set `fetchDetails` to also fetch each
ad's detail payload (slower). Schedule it from the Console to track new inventory, or add a webhook to push results
to your own system.

### Use cases

- **Conversational market research**: "find 3-room apartments under 500k in Lyon, newest first" answered live.
- **Lead enrichment**: an agent pulls every active ad from a seller before outreach.
- **Monitoring agents**: a workflow polls new inventory around a point and alerts you.
- **Price checks**: sort by price and compare similar ads for any category (cars, motorbikes, rentals...).

### Input (classic run)

| Field                                     | Description                                                                   |
| ----------------------------------------- | ----------------------------------------------------------------------------- |
| `category`                                | Category id: 9 sales, 10 rentals, 11 flat-shares, 13 offices, 12 seasonal, 8 all real estate, 2 cars, 3 motorbikes, 1 vehicles, 0 all |
| `keywords`                                | Optional free-text query                                                      |
| `departmentIds`, `regionIds`, `geo`       | Location filters (departments, regions or a radius around lat/lng)           |
| `realEstateTypes`                         | maison / appartement / terrain / parking / autre                              |
| `priceMin/Max`, `squareMin/Max`, `roomsMin/Max` | Ranges                                                                  |
| `ownerType`, `sortBy`, `sortOrder`        | Seller type and sorting                                                       |
| `fetchDetails`, `maxItems`                | Per-ad detail enrichment and result cap                                       |
| `proxyConfiguration`                      | Defaults to Apify RESIDENTIAL, France                                         |

### FAQ

**Do I need an account or cookies?** No. The Actor mints the anonymous device token the mobile app uses.

**Why a proxy?** leboncoin blocks datacenter IPs. The Actor uses Apify RESIDENTIAL proxies from France (proxy traffic
is part of your Apify usage) and rotates to a new exit when one is challenged. leboncoin's anti-bot is strict, so an
occasional tool call can fail after several exits; it is not charged and a retry normally works.

**How fresh is the data?** Live on every tool call.

**Which categories?** All of them. Real estate is the default; set `category` for cars, motorbikes and others.

**Is scraping legal?** You are responsible for complying with leboncoin's terms and applicable law. Query only public
data, respect rate limits and privacy rules, and do not use personal data of private sellers for unsolicited
marketing.

# Actor input Schema

## `category` (type: `string`):

Leboncoin category id to search. Real estate: 9 = sales, 10 = rentals, 11 = flat-shares, 13 = offices/shops, 12 = seasonal. Others: 2 = cars, 3 = motorbikes, 1 = vehicles, 8 = real estate (all).

## `keywords` (type: `string`):

Optional free-text query (e.g. 'appartement terrasse').

## `departmentIds` (type: `array`):

Filter by French department numbers, e.g. \["75", "92"] for Paris & Hauts-de-Seine.

## `regionIds` (type: `array`):

Filter by region ids, e.g. \["12"] for Île-de-France.

## `geo` (type: `object`):

Radius search around a point: { "lat": 48.8566, "lng": 2.3522, "radiusKm": 10 }.

## `realEstateTypes` (type: `array`):

Property types (real-estate categories only).

## `priceMin` (type: `integer`):

Minimum price in euros.

## `priceMax` (type: `integer`):

Maximum price in euros.

## `squareMin` (type: `integer`):

Minimum living surface in m².

## `squareMax` (type: `integer`):

Maximum living surface in m².

## `roomsMin` (type: `integer`):

Minimum number of rooms.

## `roomsMax` (type: `integer`):

Maximum number of rooms.

## `ownerType` (type: `string`):

Filter by seller type.

## `sortBy` (type: `string`):

Field to sort results by.

## `sortOrder` (type: `string`):

Ascending or descending order.

## `fetchDetails` (type: `boolean`):

Also fetch each ad's full detail payload (slower, more API calls).

## `maxItems` (type: `integer`):

Stop after this many listings (classic run).

## `proxyConfiguration` (type: `object`):

Leboncoin blocks datacenter IPs. Default is Apify RESIDENTIAL from France; each DataDome challenge rotates to a new exit automatically (proxy traffic is billed to your plan).

## Actor input object example

```json
{
  "category": "9",
  "departmentIds": [
    "75"
  ],
  "ownerType": "all",
  "sortBy": "time",
  "sortOrder": "desc",
  "fetchDetails": false,
  "maxItems": 25,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "FR"
  }
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "departmentIds": [
        "75"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ],
        "apifyProxyCountry": "FR"
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("axlymxp/leboncoin-mcp-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "departmentIds": ["75"],
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
        "apifyProxyCountry": "FR",
    },
}

# Run the Actor and wait for it to finish
run = client.actor("axlymxp/leboncoin-mcp-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "departmentIds": [
    "75"
  ],
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "FR"
  }
}' |
apify call axlymxp/leboncoin-mcp-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,axlymxp/leboncoin-mcp-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/ncM5SmN9WgAmho90b/builds/adhjoEechqQOxgHc4/openapi.json