mcp-immo

mcp-immo-olv

来自法国公共开放数据的房地产数据 提供地址后，MCP 客户端可以查询公证交易（DVF）、获取基于可比房产的估价、挂牌租金、房产税参考值、DPE、Géorisques 风险信息，以及市镇 INSEE 画像——无需 API 密钥。

此 MCP 的目标：基于可靠来源生成数据

房地产门户有时会展示要价和不透明的估价。法国公共数据提供了更好的选择：DVF 公证文件、ADEME 诊断数据、租金指标、REI 地方税务数据、风险信息和地址参考数据。mcp-immo-olv 将这些数据整合为可审计的答复。

每个数字都会注明来源、适用范围和局限。估价仍然只是对开放数据的分析，不是专业价值评估，也不是财务建议。

连接方式

唯一的前提条件：Node.js 18 或更高版本。无需 API 密钥，也无需账户。 默认情况下，服务在本地以 stdio 模式运行：不会向网络公开。可选的 Streamable HTTP 模式（变量 IMMO_HTTP_PORT）允许托管并共享服务——参见§ 6。

您的使用场景	一行命令连接
Claude Code	claude mcp add immo-olv -- npx -y mcp-immo-olv@latest
Cline	cline mcp add immo-olv --yes -- npx -y mcp-immo-olv@latest
其他 MCP 客户端	将下方 JSON 代码块复制到 mcpServers
官方 MCP 注册表	服务 io.github.OlivierLAVAUD/mcp-immo
没有 MCP 客户端	本地 Web 控制台：npm run dev → http://localhost:5173
托管 / 远程访问	IMMO_HTTP_PORT=8123 npx -y mcp-immo-olv@latest → http://127.0.0.1:8123/mcp

1. Claude Code

claude mcp add immo-olv -- npx -y mcp-immo-olv@latest

使用 claude mcp list 验证：其中应列出 immo-olv。如需使用 /immo-olv:rapport、/immo-olv:estimation 和 /immo-olv:risques 命令，请安装 插件（参见安装为 Claude Code 插件）。

2. Cline

使用一条命令（cline CLI）：

cline mcp add immo-olv --yes -- npx -y mcp-immo-olv@latest

如果不使用 --yes，该命令会打开添加助手，并预先填入这些字段。 使用 cline config mcp 验证：其中应列出已启用的 immo-olv。

从 IDE 中操作：在 Cline 面板中，点击 MCP Servers 图标（工具栏）→ Configure 选项卡 → Configure MCP Servers 按钮，然后在 mcpServers 中添加：

{
  "mcpServers": {
    "immo-olv": {
      "command": "npx",
      "args": ["-y", "mcp-immo-olv@latest"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

该扩展会打开自己的 MCP 设置文件；CLI 则读取 ~/.cline/data/settings/cline_mcp_settings.json（可通过变量 CLINE_MCP_SETTINGS_PATH 覆盖）。随后重启 Cline：21 个工具 就会显示在 MCP 工具列表中。

3. 其他所有 MCP 客户端

将此代码块复制到客户端配置（mcpServers）中：

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

重启客户端：21 个工具就会显示在其 MCP 工具列表中。

4. 从此代码库运行（开发）

npm install
npm run build

然后将客户端指向本地构建，而不是已发布的软件包：

{
  "mcpServers": {
    "immo-olv": {
      "command": "node",
      "args": ["/chemin/vers/mcp-immo-olv/dist/index.js"]
    }
  }
}

使用 Claude Code 的等效单行命令：

claude mcp add immo-olv -- node /chemin/vers/mcp-immo-olv/dist/index.js

也可以单独启动服务，但它会等待客户端通过 stdin 连接：

node dist/index.js

5. Web 控制台（无需 MCP 客户端）

npm --prefix ui install
npm run build        # le pont a besoin de dist/index.js
npm run dev          # console : http://localhost:5173

无需安装任何内容，兼容的客户端即可从官方 MCP 注册表中按名称 io.github.OlivierLAVAUD/mcp-immo 解析服务——参见 从 MCP 注册表安装。

6. 托管 / Streamable HTTP

默认情况下，服务器是由 MCP 客户端启动的 stdio 进程。设置 IMMO_HTTP_PORT 后，同一工具注册表会切换到 MCP Streamable HTTP 传输，以便托管、与团队共享，或供无法启动子进程的客户端连接。

IMMO_HTTP_PORT=8123 npx -y mcp-immo-olv@latest
# → mcp-immo-olv listening on Streamable HTTP: http://127.0.0.1:8123/mcp

将 MCP「远程」客户端指向 endpoint URL：

{
  "mcpServers": {
    "immo-olv": { "url": "http://127.0.0.1:8123/mcp" }
  }
}

变量	默认值	作用
IMMO_HTTP_PORT	(未设置 = stdio)	监听端口；设置后服务器切换到 HTTP 模式
IMMO_HTTP_HOST	127.0.0.1	绑定地址
IMMO_CACHE_DIR	(未设置 = 仅内存)	DVF 的持久磁盘缓存目录：可将冷启动时间缩短一个数量级

对外开放服务器前须知：

• 默认仅本机访问。 服务器只监听 127.0.0.1：未经身份验证的 MCP 服务器会开放整个工具面。若要让其他机器访问，请有意设置绑定地址 （IMMO_HTTP_HOST），并保护访问（使用带身份验证的反向代理、防火墙等）。 服务器端未实现身份验证。
• 会话。 每个 MCP 会话（initialize）都会获得各自的服务器／传输组合， 并通过 Mcp-Session-Id 标头进行路由。未知会话会返回 404，未授权的方法 会返回 405。
• JSON 响应。 每个工具都是一次请求／响应（没有服务器主动发起的流）， 因此服务器会直接返回 JSON——兼容 curl 和所有 Streamable HTTP 客户端 （按照规范，这些客户端必须接受 application/json 和 text/event-stream）。
• 默认仍使用 stdio。 Claude Code、Cline 或任何会启动此软件包的客户端 均不受影响：未设置 IMMO_HTTP_PORT 时，行为与之前完全相同。

从 MCP 注册表安装

该服务器已在官方 MCP 注册表中登记，名称为：

io.github.OlivierLAVAUD/mcp-immo

能够从注册表解析服务器的客户端可通过此名称找到它，无需 API 密钥或创建 账户。注册表仅存储元数据：服务器在本地以 stdio 运行，并从 npm 软件包 mcp-immo-olv 启动。上述手动配置与之等效。

# Vérifier la fiche publiée
curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.OlivierLAVAUD%2Fmcp-immo"

作为 Claude Code 插件安装

该仓库也是 Claude Code 插件市场。无需 API 密钥，只需两条命令：

claude plugin marketplace add OlivierLAVAUD/mcp-immo-olv
claude plugin install immo-olv@mcp-immo-olv

插件 immo-olv 会通过 npx -y mcp-immo-olv@latest 以 stdio 启动 MCP 服务器，并添加三个预先配置工具调用的命令：

命令	生成内容
/immo-olv:rapport <adresse>	某个地址的完整档案
/immo-olv:estimation <adresse> <type> <surface>	基于可比房产的估价，以及经过测量的模型可靠性
/immo-olv:risques <adresse>	风险、城市规划和地籍信息

此外还有一个规范说明 skill（immobilier-france），用于要求引用每个数字的来源、 绝不编造数据，并将 available: false 的风险视为未知而非不存在。

在原生 Windows 环境下，如果无法解析 npx，请手动声明服务器：

claude mcp add immo-olv -- cmd /c npx -y mcp-immo-olv@latest

工具

工具	结果	来源
property_report	完整报告：市场、销售、估值、租金、房产税、DPE、风险、市镇、地籍、PLU、IRIS、租金管制；可选 format: "markdown" 生成可分享的资料，或使用 addresses（2–5）生成按地址分类的报告	以下所有来源
compare_properties	并排比较 2 至 5 个地址：市场、估值、租金、DPE、排名	DVF + Carte des loyers + ADEME
acquisition_costs	购置费用模拟（产权转让税、公证费用、平均房产税）及毛收益率／净收益率	官方收费标准 + REI + Carte des loyers
search_by_budget	反向搜索：指定预算可覆盖哪些市镇、面积和收益率	DVF + Carte des loyers + geo.api.gouv.fr
estimate_property	基于可比房产的加权估值、估值区间、有效样本数、租金和收益率	DVF + Carte des loyers + 用于估算平均房产税的 REI
backtest_estimator	模型的滚动回测：MAPE、偏差、区间覆盖率，按面积区间和年份划分	DVF（DGFiP / Etalab）
property_sales	地址附近或市镇内的真实公证销售记录	DVF（DGFiP / Etalab）
price_per_m2	中位数、四分位数、年度变化和 12 个月窗口	DVF（DGFiP / Etalab）
rent_estimate	按细分市场划分的挂牌租金指标	Carte des loyers（住房部 / ANIL）
rent_control	参考租金、法定上限（上调后）和下限	租金管制（巴黎市、里昂大都会、蒙彼利埃）
property_tax_estimate	每个应税项目的年度平均费用，按组成部分细分	REI（DGFiP），通过 OFGL 公共 API
dpe_lookup	地址对应的能源性能诊断，涵盖现有和新建住房，包含按等级划分的出租法律状态（第 2024-501 号法令）及预估年度能源费用	ADEME（dpe03existant、dpe02neuf）
cadastral_parcel	地籍地块：标识符 idu、地籍分区、编号、官方面积	PCI、IGN / DGFiP（API Carto）
urbanism_zoning	PLU 分区（U / AU / A / N）、城市规划条例和规定	城市规划门户（DGALN / IGN）
iris_lookup	地址对应的 INSEE IRIS：代码、名称、类型、市镇	CONTOURS-IRIS / ADMINEXPRESS、IGN
nearby_amenities	地址周边设施：交通、学校、商店、医疗、绿地——指定半径内的数量和最近设施的直线距离；交通设施另按火车／地铁／有轨电车／公交车细分	OpenStreetMap（ODbL）、Overpass API
natural_risks	官方自然和技术风险	Géorisques
risk_summary	风险摘要：针对每项风险（洪水、黏土、氡、ICPE、DPE）各用一句话说明，并明确标出未知信息	Géorisques + ADEME
commune_info	人口（人口普查 + INSEE 法定人口 pmun/pcap/ptot）、邮政编码、省、地区、面积、中心点	geo.api.gouv.fr / INSEE
geocode_address / reverse_geocode	地址 ↔ 坐标、INSEE 代码和 BAN 标识符	国家地址数据库

结构化输出

这 21 个工具都声明了结果架构（outputSchema，MCP 2025-06-18 规范）。因此，每次调用都会返回相同的有效负载两次：structuredContent 是发送前经 SDK 验证的对象，另一个则是沿用已久的 JSON 文本块，为早于此版本的客户端保留。客户端可以为结果指定类型，无需重新解析即可渲染，并信任声明的结构——estimate_property 承诺提供 estimate.per_m2.estimate、estimate.confidence、estimate.top_comps[]；如果无法提供这些内容，服务端会报错，而不会返回其他内容。

架构有意保持开放（additionalProperties: true）：上游来源新增字段不会导致工具失效。架构会经过两层验证——test/output-schemas.test.ts 会将其与捕获的真实有效负载（ui/fixtures/property-report-lyon.json）进行比对，npm run smoke 则会用相同的架构验证实时响应。

房产税与“净”收益率

property_tax_estimate 绝不会声称知道某处房产的房产税通知单内容。REI 发布的是按市镇汇总的金额和应税项目数量：服务端会计算其平均税负，包括已公布的组成部分（市镇份额、跨市镇份额、工会、GEMAPI、TEOM）。实际税额取决于地籍租赁价值、免税情况、业主和征税方式：购买前请务必索取相关信息。

扣除平均税额后的收益率，是从年租金中扣除这一平均值。它不扣除共管费用、保险、管理费、空置损失、维修费用或所得税：这并非净净收益率。

示例

工具的实际输出——风险摘要、周边信息、比较、按预算搜索、Markdown 房产信息页、地址批次和错误消息——见 EXAMPLES.md，可通过 npm run examples 重新运行。

按需求和使用流程分类的21 个工具示例提示词（可复制到客户端），见 Prompts.md。其中包括用于检查防护措施的提示词：来源无法访问 → inconnu、可比房源少于 3 个时拒绝估价、地址不存在。

估价方法

估价采用可比成交价的加权中位数：房产类型相同，面积为目标面积的 40–250%，每份交易文件仅计一套住房，并剔除极端值。较早成交的价格会根据市镇最新市场年份水平进行调整（系数限制在 0.7–1.6）。权重综合考虑距离、面积相似度和成交时间；加权四分位数用于得出区间。每个可比房源、调整值和权重都会一并返回。

如果可比房源少于 3 个，估价引擎会拒绝估价。它无法获知房屋状况、楼层、景观、维修情况或法律限制。

估价引擎回测

backtest_estimator 会在市镇成交记录上重新运行估价引擎：对每笔成交进行估价时，只使用该成交日期之前登记的成交记录（按 asOf 切分，不包含该交易），然后与实际成交价比较。未来的可比房源和未来的市场水平都不会泄漏到计算中。

它会公布 MAPE、中位误差和第 90 百分位误差、有符号偏差（正值 = 模型高估），以及 P25–P75 区间的覆盖率——覆盖率应接近 50%，而非 95%：经过良好校准的 P25–P75 区间应包含一半的已完成交易。结果还会按面积区间和年份细分，并列出误差最大的 10 笔交易供审计。对 Lyon 进行的一次控制运行得出 MAPE 约为 21%、偏差为 +8%、覆盖率为 52.5%。

数据集、许可证和限制

每个数据集都链接到其官方参考页面（数据集名称为链接）； 服务在响应中返回的 URL — source_url、officialReportUrl、 unavailable.portal_url — 均由 npm run smoke 实时验证。

数据集	提供方	在服务中的用途
地理定位 DVF	DGFiP / Etalab	2021 年至今的销售记录；2021 年之前没有地理定位数据源；不包括阿尔萨斯-摩泽尔和马约特；发布有延迟
租金地图	住房部 / ANIL	模型估算的挂牌租金，含费用；并非受监管的参考租金
租金管制	巴黎市、里昂大都会和蒙彼利埃	仅限覆盖区域的参考租金；其他区域会明确返回“未覆盖”
REI	DGFiP，由 OFGL 提供	汇总的地方税务数据；按税目计算的平均值，绝不是个人税额
现有住房 DPE和新建住房 DPE	ADEME	诊断数据 dpe03existant 和 dpe02neuf，各自标注所属登记册
地籍（PCI）	IGN / DGFiP（API Carto）	地块、idu 和面积；绝不涉及所有权或建造权
城市规划地理门户	DGALN / IGN（API Carto）	具有法律约束力的分区和规定；没有 PLU 的市镇不会出现在其中
CONTOURS-IRIS / ADMINEXPRESS	IGN（数据源为 INSEE）	IRIS 标识；此图层不含社会人口数据
Géorisques	生态转型部	官方风险报告；如果其 API 无响应，响应会带有 available: false 并明确说明，而不是返回空列表
OpenStreetMap（通过 Overpass）	OSM 贡献者，ODbL	地址周边的兴趣点；覆盖情况因社区贡献而不均衡；如果 Overpass 无响应，count 为零表示未知，绝不表示“周边什么都没有”
BAN / geo.api.gouv.fr	IGN / DINUM / INSEE	地址和行政单位

许可证：此处引用的国家数据集采用开放许可证 / Open Licence（Etalab），OpenStreetMap 采用 ODbL；某些地方政府数据集有自己的许可证，重复使用前请查阅数据集页面。引用响应内容时必须注明数据源。公共数据集会实时查询，无需 API 密钥。内存缓存可降低延迟并减少重复调用，但重启后会清空；设置 IMMO_CACHE_DIR（可写目录）可将已读取的 DVF 记录持久化到磁盘 — 重启后会从文件重新载入，而不是重新下载全部数据，提供的数据不会改变。

开发

npm install
npm run build
npm test          # tests unitaires, sans réseau
npm run smoke     # vérification live des API publiques
npm run examples  # exemples live, commentés dans EXAMPLES.md

cd ui
npm install
npm run dev       # console avec hot reload : http://localhost:5173
npm run build
npm start         # console compilée + pont MCP : http://localhost:8787
npm run smoke     # test de rendu avec fixtures réelles

在项目根目录下，无需切换目录也可使用相同命令（npm run dev 会转交给 ui/）：

npm --prefix ui install
npm run dev       # console avec hot reload
npm run ui:build  # compile l'interface
npm run ui:start  # console compilée + pont MCP sur un seul port

许可证

MIT。版权所有 © 2026 Olivier LAVAUD（参见 LICENSE）。