ImotAI — Bulgarian real estate

ImotAI MCP サーバー

AI エージェント（Claude Desktop、Claude Code など）に、imotai.bg のブルガリア不動産データを読み取り専用で提供する Model Context Protocol サーバーです。

サイトの公開 API を利用する薄型のクライアントです。API キーは不要で、書き込みは行わず、個人データ（仲介業者の名前、電話番号、自由記述の説明）が API の外に出ることはありません。数値は成約価格ではなく、現在公開中の物件の希望価格に基づいています。

オンラインで使う（インストール不要）

サーバーは https://imotai.bg/mcp で稼働しています（Streamable HTTP、ステートレス、キー不要）。

• Claude（claude.ai／デスクトップアプリ）：Settings → Connectors → Add custom connector → https://imotai.bg/mcp
• Claude Code：claude mcp add --transport http imotai https://imotai.bg/mcp
• Cursor／VS Code／その他のクライアント（mcp.json）：

{ "mcpServers": { "imotai": { "url": "https://imotai.bg/mcp" } } }

• ChatGPT：https://imotai.bg/mcp を使ってカスタムコネクターを追加します（プランによっては開発者モードが必要です）。

ブルガリア語の手順：https://imotai.bg/ii-asistenti。オンライン利用の制限：クライアントあたり毎分30リクエスト。

ステータス

v0.2.0。 6つのツール（list_districts、search_properties、get_property、get_market_stats、get_market_report、estimate_value）があり、それぞれに明示的な出力許可リストを設定しています。物件関連のツールには marketContext ブロックが含まれます。トランスポートは2種類です。stdio（dist/index.js、ローカル）と Streamable HTTP（src/http.ts、上記のホスト済みエンドポイント）です。get_market_report は、都市の月次ImotAI市場レポート（中央値の希望価格／m²、前月比、地区、新規物件）を返します。

データ：CC BY 4.0 — ImotAI（imotai.bg）のクレジット表記が必要です。

インストール

git clone https://github.com/pdimiev-prog/imotai-mcp.git
cd imotai-mcp
npm install
npm run build   # produces dist/index.js

Claude Desktop で使う

claude_desktop_config.json に以下を追加します（dist/index.js には絶対パスを指定してください）。

{
  "mcpServers": {
    "imotai": {
      "command": "node",
      "args": ["/absolute/path/to/imotai-mcp/dist/index.js"],
      "env": { "IMOTAI_API_URL": "https://imotai.bg/api" }
    }
  }
}

Claude Desktop を再起動し、次のように質問します。

ImotAI がソフィアで追跡している地区と、各地区の公開中の物件数を教えてください。

Claude は list_districts を呼び出し、その結果に基づいて回答します。

ツール

list_districts

入力： { city: string } — 都市のスラッグ（"sofia"）またはブルガリア語の都市名（"София"）。

出力：

{
  "city": { "slug": "sofia", "name": "София" },
  "districts": [
    { "name": "Лозенец", "slug": "lozenets", "activeListings": 64 },
    { "name": "Витоша",  "slug": "vitosha",  "activeListings": null }
  ],
  "note": "activeListings is filled only for districts with a public price page (>= 8 offers); a null count does not mean zero."
}

都市が見つからない場合は、{ "error": "Unknown city \"…\". Recognised city slugs: …" } を返します。まずこのツールを呼び出してください。返されるスラッグは、他のツールで有効な district 値です。

search_properties

入力：

フィールド	型	備考
city	string、必須	スラッグまたはブルガリア語の都市名
transactionType	"sale" | "rent"、必須
district	string	list_districts が返すスラッグ
propertyType	enum	apartment、house、villa、studio、office、shop、warehouse、land、garage、other
minPrice / maxPrice	number	EUR
minArea / maxArea	number	m²
rooms	string	CSV。例："2,3"。5室以上の場合は "5+"
limit	integer 1–25	デフォルトは10

出力： { results: [...], total, shown }。各結果には、構造化フィールドと物件への url が含まれます。連絡先情報、自由記述の説明、座標は含まれません。

get_property

入力： { id: string } — 物件のUUIDまたはURLスラッグ。

出力： { found: true, url, ...structured fields, features: [] }。該当する物件がない場合は { found: false, reason } を返します。仲介業者の説明、電話番号／名前、正確な座標は返しません。

get_market_stats

入力： { city: string, district?: string } — list_districts が返すスラッグまたはブルガリア語の都市名・地区名。都市全体の統計を取得するには、district を省略します。

出力： { available: true, city, district, count, avgPrice, avgPricePerSqm, price: {p25,p50,p75}, pricePerSqm: {p25,p50,p75}, byRooms: [...], neighbouringDistricts: [...], basis, url }。住宅タイプ全般の売買物件が対象です。物件が8件未満の場合は { available: false, count, reason } を返します。都市または地区が見つからない場合は、list_districts を案内する { error } を返します。

市場の概要

どちらの物件ツールにも marketContext が付与されます。「この掲載物件の価格は、地区の相場より高いか低いか」を示します。

• get_property.marketContext は、ImotAI 独自の計算による、掲載物件ごとの信頼性の高い数値です。districtAveragePricePerSqm、districtMedianPricePerSqm、deviationPercent（＋は地区の相場より高いことを示します）、comparableActiveListings、basedOnCount、pricePageUrl が含まれます。
• search_properties[].marketContext は、検索結果を確認するための、地区単位の簡易的な推定値です（地区ごとに価格ページを1回参照します）。districtAveragePricePerSqm、deviationPercent、comparableListings、basis が含まれます。

地区の掲載物件が8件未満の場合、または価格ページがない場合は、どちらも null になります。2つの値では分母がわずかに異なるため、数値は近いものの一致しません。正確な値は get_property のものです。

estimate_value

入力：

フィールド	型	注記
city	string、必須	list_districts にあるスラッグまたはブルガリア語の名称
district	string、必須	list_districts にあるスラッグまたはブルガリア語の名称
propertyType	enum、必須	apartment、house、villa、studio、land
area	number、必須	居住面積（m²）
rooms	integer	指定できますが、フィルタリングには使用されません

出力：

{
  "available": true,
  "estimate": 208000,
  "rangeLow": 184000,
  "rangeHigh": 240000,
  "basedOnCount": 40,
  "confidence": "medium",          // from sample size; forced "low" for the market blend
  "disclaimer": "…",               // ALWAYS present — show verbatim
  "referenceUrl": "https://imotai.bg/ceni/sofia/lozenets"
}

比較可能な掲載物件が5件未満の場合、{ "available": false, "reason": "…", "disclaimer": "…" } を返します。この場合も disclaimer が含まれます。不明な市または地区を指定すると、list_districts を参照する { "error": "…" } を返します（この場合、disclaimer は含まれません）。

比較可能な掲載物件が50件以上の場合、confidence は high、15件以上の場合は medium、それ未満の場合は low です。外部の市場データが数値に反映された場合は、常に low となり、その旨が disclaimer に記載されます。

⚠️ これは、比較可能な掲載中の物件の現在の希望価格に対する位置付けです。査定でも、公式評価でも、成約取引に基づくものでもありません。 available の結果にはすべて disclaimer フィールドが含まれます。このツールの数値を引用する場合は、必ずその内容を変更せずにユーザーに提示してください。

レート制限

サーバーは、プロセスごとに1分あたり60件の下流リクエストを許可します（トークンバケット方式で、継続的に補充されます）。imotai.bg/api への呼び出しはすべてカウントされます。3つの地区を解決する search_properties は、4件のリクエストを消費します（検索1件＋価格ページ3件）。

トークンバケットが空の場合、ツールは例外をスローせず、次を返します。

{ "error": "Твърде много заявки за кратко — изчакайте минута." }

約1分待ってから再試行してください。制限は実行中のサーバープロセスごとに適用されます。Claude Desktop クライアントは1つのプロセスです。独自のインスタンスを実行する場合は、IMOTAI_RATE_LIMIT_PER_MIN で上書きできます。

設定

環境変数	デフォルト	意味
IMOTAI_API_URL	https://imotai.bg/api	ImotAI 公開 API のベース URL
IMOTAI_HTTP_TIMEOUT_MS	15000	リクエストごとのタイムアウト
IMOTAI_RATE_LIMIT_PER_MIN	60	1分あたりの下流リクエスト最大数（トークンバケット方式、プロセスごと）

動作の仕組み

stdio MCP サーバー（Node ≥ 20、ESM）です。各ツールは、公開されている imotai.bg/api エンドポイントに対して1～2回の呼び出しを行い、明示的に許可したフィールドのリストに基づいてレスポンスを整形します。状態、キャッシュ、認証情報は使用しません。

ライセンス

MIT。