Joomil — Swiss Classifieds MCP

joomil-mcp

面向 Joomil.ch 的 MCP 服务——瑞士领先的法语分类信息平台，自 2007 年起持续运营。

浏览并搜索 34 个类别中的 45,000 多条有效信息：房地产、车辆、工作、动物、电子产品、时尚等，全部来自瑞士法语区（Romandie）。

工具

工具	描述
suggest_filters	根据自然语言查询推断 search_classifieds 的筛选条件
search_classifieds	使用筛选条件搜索信息：关键词、类别、州（严格枚举）、地点、价格范围、排序、分页
get_classified	根据 ID 获取信息的完整详情：描述、图片、发布者、到期日期
get_categories	列出有效类别及其通过 parent_id 表示的层级关系
get_cantons	列出 canton 筛选器支持的州名称（特定于 API 的拼写）

快速开始

这是一个远程 MCP 服务——无需本地安装。

端点： 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"
  }
}

示例提示词

• “帮我在沃州找一辆价格低于 10'000 CHF 的自动挡汽车。”
• “搜索锡永的三居室公寓。”
• “Joomil 提供哪些电子产品类别？”
• “给我看看瓦莱州的复古沙发信息。”
• “搜索纳沙泰尔的酒店业招聘信息。”

给 Agent 的提示：按州筛选前，请先调用 get_cantons——API 使用的拼写可能不太直观（例如，使用 Bern 而不是 Berne，使用 Geneve 而不是 Genève/Geneva）。 对于用户的自由文本请求，请先调用 suggest_filters，然后将返回的 filters 对象传递给 search_classifieds。

API 参考

suggest_filters

参数	类型	描述
query	string	自然语言搜索请求，例如 appartement 3 pièces à Sion

返回可直接用于 search_classifieds 的 filters 对象，以及类别置信度分数；如果匹配结果不确定，还会返回警告。MCP 层会短暂缓存类别元数据，以避免每次生成建议时都重新获取类别树。

实用示例：

用户请求	典型的建议筛选条件
Tesla Model 3 moins de 25'000 CHF	q: "Tesla Model 3"、cat_id: 101、price_max: 25000、sort: "price_asc"
vélo budget 1.5k CHF	q: null、类别为运动/休闲、price_max: 1500、sort: "price_asc"
appartement 3 pièces à Sion	q: "3 pièces"、cat_id: 10255、location: "Sion"
voiture entre 10'000 et 20'000 CHF	cat_id: 101、price_min: 10000、price_max: 20000
Golf GTI dans le canton de Vaud	q: "Golf GTI"、cat_id: 101、canton: "Vaud"
canapé vintage à Lausanne	q: "vintage"、cat_id: 10022、location: "Lausanne"
iPhone 14 à Genève	q: "iPhone 14"、cat_id: 10127、location: "Genève"

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

Parameter	Type	Description
q	string	全文搜索（标题 + 描述）
cat_id	number	分类 ID——包括子分类
canton	enum	严格枚举——参见 get_cantons。Geneve、Vaud、Valais、Fribourg、Neuchatel、Jura、Bern、Argovie、Zurich、Lucerne、Bale-Ville、Etranger
location	string	城市名称或邮政编码（部分匹配）
price_min	number	最低价格，单位为 CHF
price_max	number	最高价格，单位为 CHF
sort	enum	recent（默认，最新优先）、price_asc、price_desc、views（浏览量最高）
limit	number	每页结果数（1–50，默认 20）
offset	number	分页偏移量——使用上次响应中的 next_offset

工具响应包含简短的易读摘要，随后是 content 中的紧凑序列化 JSON，以确保 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

Parameter	Type	Description
id	number	条目 ID（来自搜索结果或条目 URL）

返回完整的条目详情，包括完整描述、图片、分类路径、到期日期、推广级别和卖家详情。

get_categories

Parameter	Type	Description
parent_id	number	可选——省略表示获取全部，0 表示根分类，或使用任意分类 ID 获取其子分类

get_cantons

无参数。返回 search_classifieds 的 canton 筛选器接受的州值及其法语标签：

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

canton 筛选器始终传入 name 字段（而非 label_fr 或 code）。

数据

• 来源：Joomil.ch 公共 REST API
• 覆盖范围：45,000 多条有效条目、34 个顶级分类、190,000 多名注册用户
• 地区：瑞士（法语区——罗曼迪）
• 语言：法语
• 更新频率：实时
• 身份验证：无需验证

限制

此 MCP 服务为只读，且仅使用公开数据。

• 无写入操作：无法创建、编辑或删除条目，也无法联系卖家。
• 无需身份验证：没有用户账户、消息、收藏夹或保存的搜索。
• 无法联系卖家：不会公开电话号码和电子邮件地址——请使用条目的 url 直接打开 Joomil.ch。
• 无法发布：必须在 joomil.ch 上发布广告。
• 受限分类：根据内容政策，MCP 层会过滤掉 Erotique（28）、Rencontres & Amitié（14000）、Voyance & Astrologie（651）及其后代分类。底层 PHP API 仍可直接使用。
• 州筛选器为严格模式：只接受 get_cantons 返回的值。其他拼写形式（Berne、Genève、Geneva、GE、VD……）会被上游 API 静默忽略，导致返回所有条目而非筛选后的结果——此处的严格枚举可避免这种情况。
• 货币：所有价格均以 CHF 计价。条目的 price.amount 可能为 null（价格面议）或 0（免费）。
• 上游错误：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