AI HomeDesign MCP

AI HomeDesign MCP 服务 — 面向 Claude 的 AI 虚拟布置、房屋布置与室内设计

一个用于 AI 虚拟布置 和 房地产摄影 编辑的开源 Model Context Protocol (MCP) 服务。它将 AI HomeDesign 照片 API 转换为自然语言工具，让 Claude — 或任何 MCP 客户端 — 只需接受指令，就能进行 虚拟房屋布置、AI 室内设计、照片增强、移除杂物以及将白天场景转换为黄昏场景。

---

这是什么？

AI HomeDesign MCP Server 通过可流式传输的 HTTP，将 AI HomeDesign V3 API 封装为一组 Model Context Protocol 工具。任何兼容 MCP 的 AI 客户端 — Claude Desktop、浏览器中的 Claude、Cursor 等 — 都能用通俗的英语进行专业的 房地产照片编辑：

• 🛋️ 虚拟布置 — 按所选设计风格，用逼真的 AI 家具布置空房间。无需实体家具，几秒钟即可完成数字化 房屋布置。
• 🎨 虚拟重新布置与 AI 室内设计 — 更换现有家具，或彻底重新设计已布置家具的房间。
• ✨ 图像增强 — 调整光线、清晰度和色彩平衡，让照片满足房源展示要求。
• 🧹 移除物品 / 清理杂物 — 自动移除家具和杂物，展现整洁空间。
• 🌆 白天转黄昏 — 将白天的室外场景转换为温暖的黄昏场景。
• 🧱 墙面、地板与天花板更换 — 用雅致的 AI 效果重新设计表面。

由于它支持 MCP，无需学习 SDK — 只要描述需求，模型就会使用正确的参数调用合适的工具。

为什么通过 MCP 进行虚拟布置和房屋布置？

传统的房屋布置意味着租用家具并安排拍摄。面向房地产经纪人的虚拟布置只需编辑照片即可取代这种方式 — 但使用编辑工具仍要花费数小时，委托布置服务则要等待数天才能拿到成品。

这个服务将整个流程简化为一次对话：上传房源照片，选择风格，即可获得可下载、适合市场展示的图片。它支持多租户（每位调用者使用自己的 AI HomeDesign 密钥）、无状态且可自托管，既适用于单个经纪人，也适用于生产级 PropTech 产品。

---

可用工具

工具	功能	输入
list_capabilities	按类别列出所有工具	—
list_styles	列出允许使用的设计风格、房间类型和组件选项	—
describe_tool	显示工具的输入及可直接使用的示例载荷	工具标识
virtual_staging	按设计风格布置空房间	图片 + 风格 + 房间
virtual_restaging	更换已布置家具的房间中的家具	图片 + 风格 + 房间
interior_design	彻底重新设计已布置家具的房间	图片 + 风格 + 房间
enhance_image	改善光线、清晰度和色彩	图片
remove_items	清理杂物 / 移除家具	图片
day_to_dusk	将白天的室外场景转换为黄昏场景	图片
change_wall / change_floor / change_ceiling	重新设计表面	图片 + 房间
create_project · create_order · run_process · get_process · wait_for_result	用于全面控制的底层原语	参见 describe_tool

每个辅助工具都接受图片 URL或 base64 图片，并返回可下载的结果图片 URL。

支持的设计风格： prime、modern、farmhouse、scandinavian、hampton、industrial、traditional、contemporary。 支持的房间类型： 卧室、客厅、厨房、浴室、餐厅、家庭办公室、室外、婴儿房。

---

快速开始

选项 A — 连接到托管服务（无需设置）

1. 获取 API 密钥。 登录 aihomedesign.com， 打开 API / Developer settings，然后复制你的 x-api-key。

2. 生成连接器链接。 将密钥粘贴到 aihomedesign.com/mcp 的生成器中。密钥会在 服务端验证一次，然后以加密形式存储；你将获得一个专属端点：

   https://mcp.aihomedesign.com/aihd_<your-token>/mcp
   

   你的原始密钥绝不会出现在 URL 中。

3. 将其添加到 AI 助手。 在 Claude 中：进入设置 → 连接器 → 添加自定义 连接器，将其命名为 AI HomeDesign，然后粘贴 URL。所有工具都会 自动显示。适用于任何兼容 MCP 的客户端。

⚠️ 连接器链接不包含你的原始密钥，但它允许访问你的 账户——请像对待密码一样妥善保管。 在 AI HomeDesign 控制面板中轮换密钥会撤销此前为该密钥签发的所有链接。

服务健康检查，无需密钥：mcp.aihomedesign.com/health

选项 B — 使用 Docker 自托管

git clone https://github.com/AIHomeDesign/aihomedesign-mcp.git
cd aihomedesign-mcp
cp .env.example .env      # add your AIHD_API_KEY (and DB_DSN/TOKEN_SECRET for multi-tenant)

docker build -t aihomedesign-mcp .
docker run -p 8080:8080 --env-file .env aihomedesign-mcp

MCP 端点通过 http://localhost:8080/mcp 提供服务（可流式传输的 HTTP）， 健康检查地址为 GET /health。

选项 C — 使用 Python 本地运行

pip install -r requirements.txt
export AIHD_API_KEY=your_key_here
python app/server.py

---

配置

所有配置均通过环境变量完成——参见 .env.example。

变量	用途	默认值
AIHD_API_KEY	默认/备用 AI HomeDesign x‑api‑key	—
AIHD_API_BASE	API 基础 URL	https://api.aihomedesign.com/v3
PORT	监听端口	8080
DB_DSN	用于令牌映射和使用日志的 Postgres DSN（可选）	—
TOKEN_SECRET	用于加密静态用户密钥的 Fernet 密钥（可选）	—
MCP_CONNECTOR_BASE	用于构建连接器链接的基础地址	—
UPLOAD_DIR / PUBLIC_BASE	启用内置图片上传端点	—

安全与多租户设计

• 自带密钥： 每个请求都携带调用者自己的 AI HomeDesign 密钥；任务使用该密钥运行。
• 密钥不会出现在 URL 中： 登录页会验证密钥，然后生成一个不透明的 aihd_… 连接器令牌；原始密钥会以静态加密形式（Fernet）存储，并在每次请求时 还原。
• 使用情况日志记录每次调用的工具、状态和耗时——绝不记录原始密钥 （只记录简短且不可逆的指纹）。
• 优雅降级： 如果无法连接数据库，服务仍会继续运行。

---

工作原理

MCP client (Claude, Cursor, …)
        │  streamable HTTP  /mcp
        ▼
AI HomeDesign MCP server  ──►  AI HomeDesign V3 API  ──►  result image URLs
   (this repo)                  (api.aihomedesign.com)

该服务基于 FastMCP 和 Starlette/uvicorn 构建， 并使用纯 ASGI 身份验证中间件绑定每个请求的密钥。

技术栈

Python 3.12 · MCP（FastMCP）· Starlette · uvicorn · httpx · PostgreSQL（可选）· Docker。

常见问题

什么是 MCP 服务？

MCP 服务通过 Model Context Protocol 向 AI 模型提供工具、数据和提示词。 这是由 Anthropic 推出的开放标准。模型会在运行时发现可用工具并自行调用，因此你无需针对专有 SDK 编写胶水代码。本仓库提供的 MCP 服务，其工具用于编辑真实的房产照片。

如何用它对照片进行虚拟布置？

将服务连接到 Claude，然后发送一张空房间照片并指定一种风格—— 例如 “将这间客厅布置成斯堪的纳维亚风格。” Claude 会使用正确的参数调用 virtual_staging 工具，并返回一张可下载的逼真图片。无需手动编辑，也无需设计软件。

这个 AI 虚拟布置功能免费吗？

MCP 服务本身是开源的，并采用 MIT 许可证，因此你可以免费自托管。图片处理由 AI HomeDesign API 执行，并使用你自己的 API 密钥。

除 Claude 之外的客户端也能使用吗？

可以。它通过可流式传输的 HTTP 使用标准 MCP，因此任何兼容 MCP 的客户端—— Claude Desktop、浏览器中的 Claude、Cursor 等——都可以使用。

虚拟布置和虚拟重新布置有什么区别？

虚拟布置是为空置房间添置家具。虚拟重新布置是更换已有家具房间中的家具。如果你想彻底重新设计一个带家具的房间，而不只是更换家具，请使用 interior_design。

---

了解更多

• 🔌 一键连接：aihomedesign.com/mcp
• 🌐 网站：aihomedesign.com
• 📖 模型上下文协议：modelcontextprotocol.io

贡献

欢迎提交问题和拉取请求。请先提交问题，讨论重大更改。

许可证

根据 MIT 许可证发布。

---

_{关键词：MCP 服务 · 模型上下文协议 · Claude MCP · Anthropic MCP · MCP 工具 · 虚拟布置 · AI 虚拟布置 · 虚拟布置软件 · 房屋布置 · 面向房地产经纪人的虚拟布置 · AI 房屋设计 · AI 室内设计 · 房地产摄影 · 房地产照片编辑 · 虚拟重新布置 · 白天转黄昏 · 图像增强 · 物品移除 · 房地产 AI · PropTech。}