cn-housing-mcp
一个面向国内租房/买房场景的 MCP Server（Model Context Protocol），为智能体（OpenClaw/Cursor/Claude Desktop 等）提供统一的“房源搜索 + 房源详情结构化”工具接口。它的目标不是“暴力爬遍全网”，而是用可控、可观测、可迭代的方式把房源信息变成可分析的数据：对比表、预算测算、风险清单、看房 checklist 等都可以交给上层 skill/workflow 生成。
你能用它做什么
cn-housing-mcp 对外提供两类核心能力（两个 MCP tools）：
1) search_listings
按条件生成搜索 query，通过轻量级网页搜索拿到候选房源链接，并返回统一结构：
- 支持：城市、区域、关键词（整租/近地铁/小区名等）、租/买、价格区间、几室、limit
- 输出：候选房源列表（title/price/city/district/rooms/area/url/source/warnings…）
适合做“初筛”：先拿到一批链接，再交由 get_listing_detail 深度解析 TOP N。
2) get_listing_detail
给定房源 URL，抓取页面并进行结构化抽取，优先从以下位置提取信息：
- JSON-LD（application/ld+json）
- Next.js 数据（__NEXT_DATA__）
- 常见 meta（og:title、description 等）
输出会包含：
- 标准化字段（title/price/address/area/rooms…）
- raw_snippet（截断的原始结构化片段，便于调试）
- warnings（识别到验证码/登录要求/拒绝访问等风险提示）
为什么要做成 MCP Server？
- 解耦：MCP 只负责“取数/抽取”，上层 skill 负责“对比/测算/建议”。这样你可以更换前端（OpenClaw、Cursor、Claude Desktop）而不改后端。
- 可观测：每次返回都带 warnings 和 raw_snippet，方便快速定位“是平台拦截还是解析失败”。
- 可扩展：你可以逐步加入站点适配器（贝壳/链家/安居客/58 等），而不破坏 tool 接口。
适用范围与限制（很重要） ✅ 适合
- 半自动找房：你用平台正常浏览，mcp 负责解析/汇总/去重/结构化
- 自动化初筛：低频、低并发地从公开页面拿到候选链接 + 抓少量详情
- 以“分析与决策”为主的工作流：预算测算、风险提示、看房清单、谈判要点
❌ 不适合/不承诺
- 大规模抓取、全站爬虫、绕过验证码/反爬（不做，也不建议）
- 保证某个平台长期稳定（国内房产平台风控强、页面变动频繁）
- 替代官方 API（如果你有合规数据源，建议走 API 或导出清单）
运行方式
依赖
Python 3.10+（建议）
mcp、httpx、beautifulsoup4、lxml、pydantic
安装
pip install -r requirements.txt 启动（stdio 模式） python server.py
然后在你的 MCP 客户端（OpenClaw/Cursor/Claude Desktop）里把它配置为一个 server（command 指向 python server.py）。
可选环境变量
用于调试与稳定性调参：
HTTP_TIMEOUT：抓取超时（默认 25s）
RATE_LIMIT_SECONDS：请求间隔（默认 1.2s，建议不要太小）
USER_AGENT：自定义 UA（用于降低误伤概率）
示例：
HTTP_TIMEOUT=60 RATE_LIMIT_SECONDS=2.0 python server.py 风控与合规提示
国内房产平台普遍有严格的反自动化机制。为了避免账号/网络环境被风控：
低频请求、少翻页、少并发
遇到验证码/登录提示：请停止自动化，改为“贴链接/导出清单 → 分析”
不要在云服务器/数据中心 IP 上跑高频抓取（更容易被拦截）
cn-housing-mcp 会尽量在 warnings 中提示你可能遇到的拦截类型（captcha/login/access denied 等），帮助你快速判断失败原因。
典型工作流（推荐）
search_listings 拿 10~20 条候选链接
选 TOP 3~5 调 get_listing_detail 深度抽取
上层 skill 生成：
房源对比表（统一字段）
总成本/月供测算
风险清单 + 看房 checklist
推荐排序与理由