hemnet-mcp

Hemnet MCP

适用于**hemnet.se** 的 MCP 服务。hemnet.se 是瑞典最大的房地产门户网站。搜索待售房源、查询成交价格（slutpriser）、获取完整房源详情和照片、计算市场统计数据、解析地址，以及进行瑞典抵押贷款计算——全部通过 Claude 完成。

⚠️ 本项目由 AI（Claude）构建和维护。它通过 hemnet.se 的公开 GraphQL API 读取数据。请自行判断是否使用，并遵守 hemnet.se 的服务条款。

亮点

• 无需配置。 Hemnet 的读取查询支持匿名访问——无需登录，也无需 API 密钥。运行 npx hemnet-mcp 即可使用（只有在 Hemnet 提供 Cloudflare 挑战时才需要浏览器扩展——见下文）。
• 成交价格（slutpriser）。 Hemnet 的标志性数据集：实际成交价、要价以及高于／低于要价的百分比——经纪人评估房屋价值所需的可比数据。
• 原生适配瑞典。 货币单位为 SEK，面积单位为 m²，包含房间数、bostadsrätt 费用（avgift）、能效等级，以及遵循瑞典规则（amorteringskrav、ränteavdrag）的抵押贷款模型。
• 可嵌入。 既可作为独立 MCP 服务运行，也可作为库使用，以便集成到更大型的多门户服务中。

安装

Claude Code / Claude Desktop（npx）

{
  "mcpServers": {
    "hemnet": {
      "command": "npx",
      "args": ["-y", "hemnet-mcp"]
    }
  }
}

如果 Hemnet 提供 Cloudflare 挑战

Hemnet 有时会在其 GraphQL API 前设置 Cloudflare 机器人挑战。遇到这种情况时，服务会在默认的 HEMNET_TRANSPORT=auto 模式下切换到浏览器桥接，从你自己的浏览器中打开的 www.hemnet.se 标签页发送相同的匿名查询——无需登录 Hemnet。此功能需要安装 ContextMint Bridge 扩展，可从其发布页面获取：在 Chrome 中解压 Chrome 压缩包并以解压缩模式加载，然后在首次使用时批准配对提示。Safari 目前尚不可用（它将集成在 ContextMint 应用中，该应用尚未公开下载），所以目前请使用 Chrome。

ContextMint Bridge 是 fetchproxy 浏览器扩展更名后的版本，由同一位维护者开发——fetchproxy 自己的 README（https://github.com/chrischall/fetchproxy#extension）中也提供了它的链接。其源代码公开于 https://github.com/nullnet-app/contextmint-bridge：你可以自行构建，也可以将发布版压缩包与随附的 .sha256 文件进行校验（shasum -a 256 -c contextmint-bridge-chrome-<version>.zip.sha256）。

从源代码安装

git clone https://github.com/chrischall/hemnet-mcp
cd hemnet-mcp
npm install
npm run build
node dist/index.js

工具

工具	功能
hemnet_autocomplete_location	将地点名称（"Vasastan"）解析为 Hemnet 地点 ID——搜索的起点。
hemnet_search_listings	按地点和筛选条件（价格 SEK、房间数、平方米、房产类型、关键词）搜索在售房源。
hemnet_get_listing	获取单个房源的完整详情（价格、费用、运营成本、平方米、房间数、产权类型、能效等级、经纪人、描述、照片）。
hemnet_get_listing_photos	仅获取图库照片 URL。
hemnet_search_sold	搜索已售房源，包含最终成交价、要价以及高于或低于要价的百分比。
hemnet_get_sold_listing	获取单个已售房源的完整详情。
hemnet_get_market_stats	根据最近的 max_sales 笔成交（默认 200 笔），获取某地点的成交价中位数／平均值和每平方米价格。
hemnet_compare_listings	一次获取多个房源，以便并排比较。
hemnet_get_by_address	将自由文本街道地址解析为在售房源。
hemnet_calculate_mortgage	瑞典本地月度成本计算器（利息＋摊还＋费用，税前和税后）。不联网。
hemnet_healthcheck	检查 Hemnet GraphQL 端点是否可访问。报告探测所用的传输方式（transport：直接 fetch 或浏览器桥接，以及已配置的 HEMNET_TRANSPORT）、桥接的角色／端口／扩展链接状态（bridge，桥接存在时）、归类后的 error.kind（例如 cloudflare_challenge、session_not_ready）以及后续步骤提示。

示例流程

1. hemnet_autocomplete_location { query: "Vasastan" }
   → location_id 925970
2. hemnet_search_listings { location_ids: ["925970"], rooms_min: 2, price_max: 6000000 }
   → listing summaries
3. hemnet_get_market_stats { location_ids: ["925970"], housing_form_groups: ["APARTMENTS"] }
   → median final price, price-per-m²
4. hemnet_calculate_mortgage { price: 4695000, interest_rate: 3.9, monthly_fee: 2800 }
   → monthly cost, gross and after-tax

也可以向任意搜索工具传入自由文本 location，工具会为你解析最匹配的地点。

货币和单位

所有输出记录均使用数字：price／final_price／ fee_monthly 的单位为 SEK，living_area_sqm／land_area_sqm 的单位为 m²，rooms 为数字。只要价格和居住面积可用，始终会包含派生字段 price_per_sqm（即使 Hemnet 未提供该字段，独栋住宅中这种情况很常见）。原始的 Hemnet 格式字符串也会一并保留，字段名为 *_formatted。

库的使用

hemnet-mcp 也可以作为模块导入，因此可在较大型项目中作为 Hemnet 门户数据源 使用（例如跨门户房地产编排器）：

import { createHemnetClient, computeMarketStats } from 'hemnet-mcp';

const hemnet = createHemnetClient();
const { cards } = await hemnet.searchSales({ locationIds: ['925970'] }, { limit: 50 });
const stats = computeMarketStats(cards.map(formatSaleCard));

库入口（import … from 'hemnet-mcp'）会重新导出客户端、 规范化记录类型、纯派生函数 （computeMarketStats、calculateSwedishMortgage、货币／URL 辅助函数）， 以及所有工具注册器（registerHemnetTools(server, client)，用于将工具添加到你自己的 MCP 服务中）。

开发

npm test               # vitest (mocked transport, no network)
npm run test:coverage  # 100% coverage enforced on src/**
npm run typecheck
npm run build

测试通过内存中的模拟传输驱动每个工具和客户端——不会调用实时 hemnet.se。有关架构、 GraphQL 的特殊处理以及贡献规范，请参阅 CLAUDE.md。

许可证

MIT