willhaben-mcp

一个 MCP 服务器，让 AI 可以搜索 willhaben.at 市场中的商品列表，并获取广告的完整详情。它封装了 willhaben 逆向工程的移动应用 API，并把这些的重要字段返回给 AI。

工具

search_willhaben(keyword, ...)

在市场中进行搜索。如果传入了 category，则 keyword 是可选的。

筛选条件：

• category（id 或名称）

• condition（全新、二手、翻新等）

• clothing_size 和 shoe_size

• color、pattern

• brand

• 地区、卖家类型、价格范围、Bag, PayLivery、最近 48 小时

• 排序和分页

返回精简后的命中列表。

get_ad_detail(ad_id)

获取单个广告的一切信息：完整（未截断）的描述、所有图片、逐项属性、类别路径和精确位置。将它用在搜索返回的 id 上即可。

list_categories(query, parent_id)

为 category 过滤器查找类别 id。

• query：按名称查找整个类别树

• parent_id：向下浏览一层（两者都可填，以在逛根级类别）

完整类别树（约 3500 个类别）随服务器附在 category-tree.json 中。

search_brands(category, term)

品牌是类别特定的，并且每个类别的品牌有上百个，所以这是一个自动补全工具。传入类别和搜索词来获取匹配的品牌 id，然后将 id 交给 search_willhaben(brand=...)。

注意：condition、sizes、color、pattern 和 brand 都因类别而异；在宽泛的类别中使用它们可能会返回零结果，所以请先深入具体的子类别。

Related MCP server: Begagnad MCP

设置

pip install -r requirements.txt

运行

python main.py

服务器通过 Streamable HTTP 启动，并打印它监听的地址：

Starting willhaben-mcp server on http://127.0.0.1:8000/mcp

将你的 MCP 客户端指向该 URL。主机、端口和路径位于 main.py 顶部。

备注

• 详情 API 由静态应用令牌保护，并且只支持 HTTP/2。这两者都在 main.py 中处理。如果 willhaben 轮换令牌，请从应用的请求头中获取新令牌，并更新 WH_APPLICATION_TOKEN。

• category-tree.json 是 willhaben 市场类别树（id、label、parentId、children）的构建快照。main.py 在启动时会加载它，用于 category 过滤器和 list_categories。如果分类发生了改变，请重新获取它。

• API 的详细说明见 search_api.md。

• 这里使用了 willhaben 的内部 API，而不是官方 API。请友好地对待它。

免责声明

这是一个独立、非官方的项目，与 willhaben 不存在从属、认可或关联关系。“willhaben”及所有相关商标均由其他所有者所有。

它的发布仅用于教育和研究目的。它访问的是 willhaben 的内部 API，该 API 并非面向公众使用，可能随时断开或变更。你需对使用方式负责：请遵循 willhaben 的服务条款、robots 规则以及适用法律，不要频繁冲击其服务器，也不要处理列表中的个人数据。本服务不提供任何保证；使用风险自负。

如果你是权利持有者，并且对此项目有疑问，请通过 issue 提出，我会及时进行回复。

许可证

MIT LICENSE。按“原样”提供，不附带任何保证。