hemnet-mcp

Hemnet MCP

スウェーデン最大の不動産ポータルである hemnet.se 向けの MCP サーバーです。販売中の物件を検索し、 売却価格（slutpriser）を調べ、物件の詳細情報や写真を取得し、 市場統計を算出し、住所を特定し、スウェーデンの住宅ローンを 計算できます。すべて Claude から利用できます。

⚠️ このプロジェクトはAI（Claude）が構築・保守しています。公開 GraphQL API を通じて hemnet.se にアクセスします。ご自身の判断と 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 用 zip を解凍して展開済みの拡張機能として読み込み、初回に表示されるペアリングのプロンプトを承認してください。Safari にはまだ対応していません（一般公開ダウンロードのない ContextMint アプリ内で提供される予定です）。現時点では Chrome をお使いください。

ContextMint Bridge は、同じメンテナーによる fetchproxy ブラウザー拡張機能の新しい名称です。fetchproxy の README （https://github.com/chrischall/fetchproxy#extension）からも案内されています。ソースコードは https://github.com/nullnet-app/contextmint-bridge で公開されています。ご自身でビルドするか、リリースの zip を 同梱されている .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、部屋数、m²、物件タイプ、キーワード）を指定して、販売中の物件を検索します。
hemnet_get_listing	1件の物件の詳細情報（価格、管理費、維持費、m²、部屋数、所有形態、エネルギー性能クラス、仲介業者、説明、写真）を取得します。
hemnet_get_listing_photos	ギャラリーの写真 URL のみを取得します。
hemnet_search_sold	成約済み物件を、成約価格、希望価格、希望価格との差（％）とともに検索します。
hemnet_get_sold_listing	成約済み物件1件の詳細情報を取得します。
hemnet_get_market_stats	直近の max_sales 件の成約（デフォルトは200件）をもとに、地域の成約価格と1m²あたりの価格の中央値・平均値を取得します。
hemnet_compare_listings	複数の物件を一度に取得して、並べて比較します。
hemnet_get_by_address	自由入力の住所を、掲載中の物件に解決します。
hemnet_calculate_mortgage	スウェーデンの月額費用をローカルで計算します（利息＋元本返済＋管理費、税引前・税引後）。ネットワークは使用しません。
hemnet_healthcheck	Hemnet GraphQL エンドポイントに到達できるか確認します。プローブに使用したトランスポート（直接フェッチまたはブラウザーブリッジ、および設定された HEMNET_TRANSPORT）、ブリッジの役割・ポート・拡張機能のリンク状態（ブリッジが存在する場合）、分類された 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