ImotAI — Bulgarian real estate

ImotAI MCP Server

一个 Model Context Protocol 服务，为 AI Agent（Claude Desktop、Claude Code 等）提供一个只读窗口，用于查看来自 imotai.bg 的保加利亚 房地产数据。

它是对网站公共 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。 六个工具（list_districts、search_properties、get_property、 get_market_stats、get_market_report、estimate_value），每个工具都有明确的输出白名单；房源工具包含一个 marketContext 区块。支持两种传输方式：stdio （dist/index.js，本地）和 Streamable HTTP（src/http.ts，即上述托管端点）。 get_market_report 返回某个城市的 ImotAI 月度市场报告（每平方米挂牌价中位数、月环比变化、城区、新上架房源）。

数据：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 } — 城市 slug（"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: …" }。 请先调用此工具——它返回的 slug 是其他工具可用的 district 值。

search_properties

输入：

字段	类型	说明
city	string，必填	slug 或保加利亚语名称
transactionType	"sale" | "rent"，必填
district	string	来自 list_districts 的 slug
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 slug。

输出： { found: true, url, ...structured fields, features: [] }，如果没有此房源，则返回 { found: false, reason }。绝不会返回经纪人描述、电话/姓名或精确坐标。

get_market_stats

输入： { city: string, district?: string } — 来自 list_districts 的 slug 或保加利亚语名称。省略 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 是用于快速浏览的轻量级区域估算（每个不同区域查询一次价格页面）：districtAveragePricePerSqm、deviationPercent、comparableListings、basis。

当区域内的房源少于 8 套或没有价格页面时，两者均为 null。两者使用的分母略有不同，因此数值接近但并不完全相同；get_property 的数值更精确。

estimate_value

输入：

字段	类型	说明
city	string，必填	来自 list_districts 的 slug 或保加利亚语名称
district	string，必填	来自 list_districts 的 slug 或保加利亚语名称
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。城市或区域名称未知时，会返回 { "error": "…" } 并指向 list_districts（此时不包含 disclaimer）。

当可比房源数 ≥ 50 时，confidence 为 high；≥ 15 时为 medium；否则为 low。如果数据中混入了外部市场数据，confidence 始终为 low，且 disclaimer 会注明这一点。

⚠️ 此结果是将房源与当前在售的可比房源价格进行对比，并非评估报告或官方估值，也不基于已成交的交易。 每个 available 结果都包含 disclaimer 字段；引用此工具提供的任何数值时，都必须原样向用户展示该字段内容。

速率限制

该服务每个进程每分钟最多允许 60 个下游请求（令牌桶，持续补充）。每次调用 imotai.bg/api 都会计入限制；例如，search_properties 查询三个不同区域时会消耗四个请求（一次搜索 + 三个价格页面）。

令牌桶耗尽时，工具不会抛出异常，而是返回：

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

等待约一分钟后重试。限制按运行中的服务进程计算；单个 Claude Desktop 客户端就是一个进程。运行自己的实例时，可通过 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	每分钟最多下游请求数（令牌桶，按进程计算）

工作原理

这是一个使用 stdio 的 MCP 服务（Node ≥ 20，ESM）。每个工具会调用一次或两次公共 imotai.bg/api 端点，并通过显式字段白名单重新整理响应。无状态、无缓存、无凭据。

许可证

MIT。