onehome-mcp

onehome-mcp

适用于 OneHome（CoreLogic）的 MCP 服务——搜索房地产经纪人为你整理的房源，获取房产详情和照片，并排比较房屋，还可在 Claude 中进行抵押贷款和购房能力计算。

与 zillow-mcp、redfin-mcp、compass-mcp 和 homes-mcp 是姊妹项目。工具使用体验相同，但上游身份验证方式不同。

本项目由 AI（Claude）开发并维护。请自行决定是否使用。

OneHome 有何不同

OneHome 不是公开房源网站。买家通常通过经纪人发来的魔法链接访问该网站，例如 https://portal.onehome.com/...?token=eyJ...。其中的 token 查询参数就是门户 SPA 传递给每个 GraphQL 请求的用户专属 bearer。

因此，onehome-mcp 不像其他房地产 MCP 那样通过已登录的浏览器标签页转发每次请求，而是直接从 Node 向 services.onehome.com/graphql 发送请求，并附上 Authorization: Bearer <jwt>。我们支持以下三种获取 bearer 的方式：

模式	启用方式	说明
env_token	ONEHOME_TOKEN=<jwt>	从开发者工具的 Network 面板粘贴原始 bearer。最直接的方式。
magic_link	ONEHOME_MAGIC_LINK=https://portal.onehome.com/...?token=...	粘贴经纪人发来的完整 URL——我们会提取 token 参数。
fetchproxy_capture	（无需环境变量）+ 安装 ContextMint Bridge 浏览器扩展（Chrome：解压加载发行包中的 chrome zip；Safari 目前尚不可用——该扩展之后会集成在 ContextMint 应用中，因此暂时请使用 Chrome）+ 已登录的 portal.onehome.com 标签页	我们会等待你的标签页发出任意 GraphQL 请求，截取 Authorization 标头并重复使用。

ContextMint Bridge 是 fetchproxy 浏览器扩展的新名称，由同一位维护者开发。fetchproxy 自身的 README（fetchproxy#extension）也指向该扩展。其源代码公开于 nullnet-app/contextmint-bridge：你可以自行构建，也可以使用旁边发布的 .sha256 文件校验发行版 zip（shasum -a 256 -c contextmint-bridge-chrome-<version>.zip.sha256）。

工具

工具	功能
onehome_get_user	最精简的身份验证探测——返回你的 OneHome 个人资料（姓名、电子邮件）以及 Agent 与你共享的群组。
onehome_get_groups	列出 Agent 与你共享的 OneHome“群组”（每个群组都是一个市场／精选房源列表集合）。
onehome_get_saved_search	按 ID 获取 Agent 精选的已保存搜索——包括名称、筛选条件、多边形，以及构成共享内容的 OSK 房源 ID。
onehome_get_saved_search_with_listings	一次往返即可完成“显示我已保存的房源”流程——返回已保存的搜索及其展开后的房源。
onehome_search_properties	搜索群组中的房源；可选按已保存的搜索限定范围。
onehome_search_suggestions	在所有信息源中搜索自由文本建议（地址、MLS #）。
onehome_get_by_address	将单个自由文本街道地址解析为房源的门户 URL 和 ID。
onehome_resolve_addresses	批量将最多 100 个结构化地址解析为门户 URL 和房源 ID；并发处理，逐行捕获错误。
onehome_get_property	按房源 ID 或门户 URL 获取完整的房产记录。
onehome_bulk_get	一次调用获取最多 N 套房源——每个 ID 返回一行结构化结果，并逐行捕获错误。
onehome_get_property_photos	完整的媒体图库——提供缩略图／中等／大图版本及房间描述。
onehome_compare_properties	并排比较 2-8 套房源。逐行捕获错误；并发调用。
onehome_get_schools	获取指定纬度／经度附近由 Local-Logic 提供的小学和高中。
onehome_get_walk_score	获取 Local-Logic 提供的步行／公共交通／骑行／驾车便利度评分。
onehome_graphql	面向高级用户的备用入口——发送带变量的原始只读 GraphQL 文档（仅限查询；拒绝变更和订阅）。
onehome_calculate_mortgage	本地 PITI 计算器。计算方式与其他房地产 MCP 相同。
onehome_calculate_affordability	本地 28/36 DTI 求解器——计算你能负担的最高房价。
onehome_set_auth	在运行时添加另一个已通过身份验证的会话（magic link / JWT / email-token），供在多个 Agent 处持有共享房源的买家使用。
onehome_set_active_session	强制指定已注册会话成为当前活动会话（覆盖基于 MLS 后缀的路由）。
onehome_get_session_context	列出每个已注册会话——身份验证模式、令牌过期时间，以及各会话初始化时获取的群组／已保存搜索／Agent 范围。
onehome_healthcheck	端到端身份验证和 GraphQL 冒烟测试，并提供令牌过期诊断。

安装

最简单的方式是安装已发布的 Claude 插件（.mcpb）。其设置可选填 OneHome magic link 或 bearer token（两者均作为敏感值存储）；若两项都留空，则改用浏览器桥接捕获。用于本地开发：

git clone https://github.com/chrischall/onehome-mcp
cd onehome-mcp
npm install
npm run build

然后，将 MCP 主机指向 node /abs/path/to/onehome-mcp/dist/bundle.js，并选择以下其中一种方式：

// claude_desktop_config.json
{
  "mcpServers": {
    "onehome-mcp": {
      "command": "node",
      "args": ["/abs/path/to/onehome-mcp/dist/bundle.js"],
      "env": {
        "ONEHOME_MAGIC_LINK": "https://portal.onehome.com/en-US/properties/map?token=eyJ..."
      }
    }
  }
}

开发

npm test               # vitest, mocked transport, no network
npm run test:watch
npm run test:coverage
npx tsc --noEmit
npm run build          # tsc --noEmit + esbuild → dist/bundle.js

测试使用 FakeTransport（位于 tests/helpers.ts），它会注册每个 operationName 对应的处理程序——测试套件不会连接实时网络。tests/index.test.ts 冒烟检查会将 src/index.ts 使用的同一组工具注册加载到内存中的 MCP 客户端／服务端配对中，因此，“我写了工具文件，却忘了将其接入”这类错误会立刻暴露出来。

许可证

MIT。