joomil-mcp

MCP-сервер для Joomil.ch — ведущей франкоязычной площадки объявлений Швейцарии, работающей с 2007 года.

Просматривайте и ищите более 45 000 активных объявлений в 34 категориях: недвижимость, транспорт, работа, животные, электроника, мода и многое другое — всё из франкоязычных регионов Швейцарии (Романдия).

Инструменты

Related MCP server: willhaben-mcp

Быстрый старт

Это удалённый MCP-сервер — локальная установка не требуется.

Endpoint: https://joomil-mcp.snowy-surf-deec.workers.dev/mcp

Claude Desktop

Добавьте в ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "joomil": {
      "command": "npx",
      "args": ["mcp-remote", "https://joomil-mcp.snowy-surf-deec.workers.dev/mcp"]
    }
  }
}

Cursor

Добавьте в настройки MCP:

{
  "joomil": {
    "url": "https://joomil-mcp.snowy-surf-deec.workers.dev/mcp"
  }
}

Примеры запросов

• "Trouve-moi une voiture automatique à moins de 10'000 CHF dans le canton de Vaud."

• "Cherche un appartement 3 pièces à Sion."

• "Quelles catégories d'électronique propose Joomil ?"

• "Montre-moi les annonces de canapés vintage en Valais."

• "Cherche des offres d'emploi dans l'hôtellerie à Neuchâtel."

Совет для агентов: вызывайте get_cantons перед фильтрацией по кантону — API использует неочевидные написания (например, Bern вместо Berne, Geneve вместо Genève/Geneva). Для запросов в свободной форме сначала вызовите suggest_filters, затем передайте возвращённый объект filters в search_classifieds.

Справочник API

suggest_filters

Возвращает готовый к использованию объект filters для search_classifieds, а также оценку уверенности категории и предупреждения при неоднозначном сопоставлении. Метаданные категорий кратковременно кэшируются MCP-слоем, чтобы не перезагружать дерево категорий для каждого предложения.

Полезные примеры:

{
  "query": "appartement 3 pièces à Sion",
  "filters": {
    "q": "3 pièces",
    "cat_id": 10255,
    "canton": null,
    "location": "Sion",
    "price_min": null,
    "price_max": null,
    "sort": "recent",
    "limit": 20
  },
  "category": {
    "id": 10255,
    "name": "Appartements",
    "url": "https://www.joomil.ch/annonces/immobilier/locations/appartements/10255",
    "parent_id": 339,
    "confidence": 0.82,
    "reason": "requête immobilière appartement"
  },
  "confidence": 0.74,
  "warnings": [],
  "next_step": "Call search_classifieds with the filters object. Adjust q or cat_id if the result set is too broad."
}

search_classifieds

Ответы инструмента включают краткое человекочитаемое резюме, за которым следует компактный сериализованный JSON в content для обратной совместимости MCP. Полные данные также возвращаются в structuredContent с results, total, limit, offset, has_more, next_offset и filtered_out (элементы, удалённые с текущей страницы из-за ограничений категорий на стороне MCP).

Форма результата (каждый элемент):

{
  "id": 366872, "title": "Maison avec étangs",
  "price": { "amount": 237977.5, "currency": "CHF" },
  "location": { "city": "Saint Eugène", "postal_code": "71320", "canton": "Geneve", "country": "FR" },
  "category": { "id": 10261, "name": "Maisons & Villas", "url": "https://..." },
  "url": "https://www.joomil.ch/annonce/.../366872",
  "created_at": "2026-06-26T22:17:11+02:00",
  "has_picture": true,
  "seller": { "name": "jpclair", "certified": false }
}

get_classified

Возвращает полные детали объявления, включая полное описание, изображения, путь категории, дату истечения, уровень продвижения и данные продавца.

get_categories

get_cantons

Без параметров. Возвращает значения кантонов, принимаемые фильтром canton в search_classifieds, с их французскими названиями:

{
  "cantons": [
    { "name": "Geneve", "label_fr": "Genève", "code": "GE", "region": "Romandie" },
    { "name": "Bern", "label_fr": "Berne", "code": "BE", "region": "Suisse alémanique" }
  ],
  "total": 12
}

Всегда передавайте поле name (не label_fr и не code) в фильтр canton.

Данные

• Источник: публичный REST API Joomil.ch

• Охват: более 45 000 активных объявлений, 34 корневые категории, более 190 000 зарегистрированных пользователей

• Расположение: Швейцария (франкоязычные регионы — Романдия)

• Язык: французский

• Частота обновления: в реальном времени

• Аутентификация: не требуется

Ограничения

Этот MCP-сервер только для чтения и использует только публичные данные.

• Нет операций записи: нельзя создавать, редактировать или удалять объявления; нельзя связываться с продавцами.

• Нет аутентификации: нет учётных записей, сообщений, избранного или сохранённых поисков.

• Нет контакта с продавцом: номера телефонов и адреса электронной почты не раскрываются — используйте url объявления, чтобы открыть Joomil.ch напрямую.

• Нет публикации: размещение объявления должно выполняться на joomil.ch.

• Ограниченные категории: Erotique (28), Rencontres & Amitié (14000), Voyance & Astrologie (651) и их подкатегории отфильтровываются MCP-слоем в соответствии с политикой контента. Базовый PHP API остаётся доступным для прямого использования.

• Строгий фильтр кантона: принимаются только значения, возвращаемые get_cantons. Другие написания (Berne, Genève, Geneva, GE, VD...) молча игнорируются вышестоящим API и вернули бы все объявления вместо отфильтрованного набора — строгий enum здесь предотвращает это.

• Валюта: все цены указаны в CHF. Объявления могут иметь price.amount: null (цена по запросу) или 0 (бесплатно).

• Ошибки вышестоящего API: сбои Joomil API возвращаются как ошибки инструмента MCP с isError: true.

Разверните свой собственный

git clone https://github.com/Valmo-Sarl/joomil-mcp
cd joomil-mcp
npm install
npx wrangler login
npm run deploy

Лицензия

MIT