内容
# onehome-mcp
[](https://github.com/chrischall/onehome-mcp/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/onehome-mcp)
[](LICENSE)
OneHome 中介服务器（MCP）— 搜索您的房地产代理为您策划的列表，获取房产详细信息 + 照片，比较房屋，并从 Claude 中运行抵押贷款 / 负担能力计算。
与 [zillow-mcp](https://github.com/chrischall/zillow-mcp)、[redfin-mcp](https://github.com/chrischall/redfin-mcp)、[compass-mcp](https://github.com/chrischall/compass-mcp) 和 [homes-mcp](https://github.com/chrischall/homes-mcp) 是姊妹项目。相同的工具设计，不同的上游身份验证模型。
> 本项目由 AI（Claude）开发和维护。请自行判断使用风险。
## OneHome 有何不同
OneHome 不是一个公开的列表网站。买家通常通过代理发送的神奇链接访问它 — `https://portal.onehome.com/...?token=eyJ...`。该 `token` 查询参数是每个用户使用的 bearer，门户 SPA 将其传递给每个 GraphQL 请求。
因此，`onehome-mcp` 直接与 `services.onehome.com/graphql` 进行通信，并附带 `Authorization: Bearer <jwt>`，而不是通过您已登录的浏览器标签路由每个获取请求（像其他房地产 MCP 一样）。我们支持三种获取 bearer 的方式：
| 模式 | 如何启用 | 备注 |
| --- | --- | --- |
| `env_token` | `ONEHOME_TOKEN=<jwt>` | 直接粘贴开发工具网络面板中的 bearer。 |
| `magic_link` | `ONEHOME_MAGIC_LINK=https://portal.onehome.com/...?token=...` | 粘贴代理发送给您的完整 URL — 我们提取 `token` 参数。 |
| `fetchproxy_capture` | （无 env）+ [fetchproxy 扩展](https://github.com/chrischall/fetchproxy) 已安装 + 已登录 `portal.onehome.com` 标签 | 我们等待您的标签发出任何 GraphQL 请求，捕获 Authorization 头部，然后重用它。 |
## 工具
| 工具 | 功能 |
| --- | --- |
| `onehome_get_user` | 最小的身份验证探针 — 返回您的 OneHome 个人资料（姓名，电子邮件）和代理分享的群组。 |
| `onehome_get_groups` | 列出 OneHome 群组 — 您的代理分享给您的群组（每个群组是一个市场 / 精选列表桶）。 |
| `onehome_get_saved_search` | 按 ID 获取代理策划的保存搜索 — 名称，筛选条件，多边形和构成分享的 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` | 附近的本地逻辑小学 + 高中。 |
| `onehome_get_walk_score` | 本地逻辑步行 / 交通 / 自行车 / 汽车友好度评分。 |
| `onehome_graphql` | 强用户逃生通道 — 发送带有变量的原始 GraphQL 文档。 |
| `onehome_calculate_mortgage` | 本地 PITI 计算器。与其他房地产 MCP 相同的数学运算。 |
| `onehome_calculate_affordability` | 本地 28/36 DTI 求解器 — 您能负担得起的最大房屋价格。 |
| `onehome_set_auth` | 在运行时添加另一个身份验证会话（神奇链接 / JWT / 电子邮件令牌）供购买者跨多个代理持有股份。 |
| `onehome_set_active_session` | 强制特定注册会话成为活动会话（覆盖 MLS 后缀路由）。 |
| `onehome_get_session_context` | 列出每个注册会话 — 身份验证模式，令牌过期时间和每个启动的群组 / 保存搜索 / 代理范围。 |
| `onehome_healthcheck` | 带有令牌过期诊断的端到端身份验证 + GraphQL 烟雾检查。 |
## 安装
最简单的路径是发布的 Claude 插件（`.mcpb` 安装）。对于本地开发：
```bash
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`：
```jsonc
// 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..."
}
}
}
}
```
## 开发
```bash
npm test # vitest，模拟传输，无网络
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` 烟雾检查加载与内存 MCP 客户端/服务器对使用的相同工具注册，`src/index.ts` 使用的工具注册，因此“I 编写了工具文件但忘记连接它”错误会大声失败。
## 许可证
MIT。
