AI HomeDesign MCP

Official20 toolsLive

by AIHomeDesign · Python

MCP server to virtually stage, redesign, enhance and declutter real-estate photos.

Topics

claudeinterior-designmcpmcp-servermodel-context-protocolproptechpythonreal-estatereal-estate-photographyvirtual-stagingai-interior-designanthropic-mcpclaude-mcphome-stagingmcp-toolsreal-estate-aivirtual-staging-softwareai-home-designreal-estate-photo-editingvirtual-staging-ai

Captured live from the server via tools/list.

list_capabilities

List every AI HomeDesign tool this MCP can run, grouped by category. Returns each tool's slug, display name, description and whether it needs one or two input images. Start here to discover what is available.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "title": "list_capabilitiesArguments"
}

list_styles

List the allowed design styles, room types and widget options. With no argument, returns the global style/room/area lists. With a tool_slug, returns that tool's widgets and their allowed values. The staging/design helpers ONLY accept these values — anything else is rejected before calling the API.

Parameters1

tool_slug

string

optional

Raw schema

{
  "type": "object",
  "properties": {
    "tool_slug": {
      "default": "",
      "title": "Tool Slug",
      "type": "string"
    }
  },
  "title": "list_stylesArguments"
}

describe_tool

Show the input slots, widgets and selectable options for one tool, plus a ready-to-use example payload for `run_process`. Use this before `run_process` when you need the exact widget/item slugs for a tool.

Parameters1

tool_slug

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "tool_slug": {
      "title": "Tool Slug",
      "type": "string"
    }
  },
  "required": [
    "tool_slug"
  ],
  "title": "describe_toolArguments"
}

create_project

Create a project (a container that groups all work for one property). Returns the new project's `id`.

Parameters1

address

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "address": {
      "title": "Address",
      "type": "string"
    }
  },
  "required": [
    "address"
  ],
  "title": "create_projectArguments"
}

list_projects

List your projects (paginated). Optional free-text `search` on address.

Parameters3

page	integer	optional
limit	integer	optional
search	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "page": {
      "default": 1,
      "title": "Page",
      "type": "integer"
    },
    "limit": {
      "default": 10,
      "title": "Limit",
      "type": "integer"
    },
    "search": {
      "default": "",
      "title": "Search",
      "type": "string"
    }
  },
  "title": "list_projectsArguments"
}

get_project

Fetch a single project by id.

Parameters1

project_id

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "project_id": {
      "title": "Project Id",
      "type": "string"
    }
  },
  "required": [
    "project_id"
  ],
  "title": "get_projectArguments"
}

create_order

Upload one or more images and create an order. Provide `image_urls` (public URLs) and/or `image_base64` (raw base64 or data: URLs) — you can use either. Returns `order_id` and an `assets` list whose `id`s you map to a tool's input slot when running a process. For two-image tools pass roles like ['primary_angle','secondary_angle'] (or 'mask' for mask tools).

Parameters4

image_urls	any	optional
image_base64	any	optional
project_id	string	optional
asset_roles	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "image_urls": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Image Urls"
    },
    "image_base64": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Image Base64"
    },
    "project_id": {
      "default": "",
      "title": "Project Id",
      "type": "string"
    },
    "asset_roles": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Asset Roles"
    }
  },
  "title": "create_orderArguments"
}

get_order

Fetch an order, including its input assets and any processes run on it.

Parameters1

order_id

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "order_id": {
      "title": "Order Id",
      "type": "string"
    }
  },
  "required": [
    "order_id"
  ],
  "title": "get_orderArguments"
}

run_process

Start an AI job on an existing order (full control over every tool). `asset_map` maps each of the tool's input-slot keys to an asset id from the order. `widgets` is the raw list of {slug, item_slugs}. Use `describe_tool` to get the exact slugs. Returns `process_ids` to poll with `get_process`.

Parameters5

order_id	string	required
tool	string	required
asset_map	object	required
widgets	any	optional
process_group_id	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "order_id": {
      "title": "Order Id",
      "type": "string"
    },
    "tool": {
      "title": "Tool",
      "type": "string"
    },
    "asset_map": {
      "additionalProperties": true,
      "title": "Asset Map",
      "type": "object"
    },
    "widgets": {
      "anyOf": [
        {
          "items": {},
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Widgets"
    },
    "process_group_id": {
      "default": "",
      "title": "Process Group Id",
      "type": "string"
    }
  },
  "required": [
    "order_id",
    "tool",
    "asset_map"
  ],
  "title": "run_processArguments"
}

get_process

Fetch a process: its `status` (pending/processing/done/failed) and, when done, the `final_assets` with downloadable result image URLs. If a webhook result has already arrived for this process, it is returned immediately.

Parameters1

process_id

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "process_id": {
      "title": "Process Id",
      "type": "string"
    }
  },
  "required": [
    "process_id"
  ],
  "title": "get_processArguments"
}

wait_for_result

Poll a process until it is `done` or `failed` (or until timeout), then return the final result image URLs. Respects the API's 5s minimum poll interval.

Parameters3

process_id	string	required
timeout_seconds	integer	optional
poll_seconds	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "process_id": {
      "title": "Process Id",
      "type": "string"
    },
    "timeout_seconds": {
      "default": 180,
      "title": "Timeout Seconds",
      "type": "integer"
    },
    "poll_seconds": {
      "default": 6,
      "title": "Poll Seconds",
      "type": "integer"
    }
  },
  "required": [
    "process_id"
  ],
  "title": "wait_for_resultArguments"
}

virtual_staging

Furnish an EMPTY room photo with AI furniture in a chosen design style. Provide the photo as `image_url` OR `image_base64` (raw base64 or a data: URL). WORKFLOW — follow exactly: • Do NOT choose a `style` yourself. Call this first with style empty; it returns the list of design styles. Present them to the user and let THEM pick, then call again with their chosen style. • Detect `space` (room type) from the image yourself and pass it (bedroom, kitchen, living-room, ...). Only if you truly cannot tell, leave it empty and the tool will ask the user.

Parameters6

image_url	string	optional
style	string	optional
space	string	optional
image_base64	string	optional
wait	boolean	optional
project_id	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "image_url": {
      "default": "",
      "title": "Image Url",
      "type": "string"
    },
    "style": {
      "default": "",
      "title": "Style",
      "type": "string"
    },
    "space": {
      "default": "",
      "title": "Space",
      "type": "string"
    },
    "image_base64": {
      "default": "",
      "title": "Image Base64",
      "type": "string"
    },
    "wait": {
      "default": true,
      "title": "Wait",
      "type": "boolean"
    },
    "project_id": {
      "default": "",
      "title": "Project Id",
      "type": "string"
    }
  },
  "title": "virtual_stagingArguments"
}

interior_design

Fully redesign a FURNISHED room (walls, floors, furniture, decor) in a style. Same workflow as virtual_staging: never pick the style yourself — ask the user; detect the room type from the image. Provide image_url OR image_base64.

Parameters6

image_url	string	optional
style	string	optional
space	string	optional
image_base64	string	optional
wait	boolean	optional
project_id	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "image_url": {
      "default": "",
      "title": "Image Url",
      "type": "string"
    },
    "style": {
      "default": "",
      "title": "Style",
      "type": "string"
    },
    "space": {
      "default": "",
      "title": "Space",
      "type": "string"
    },
    "image_base64": {
      "default": "",
      "title": "Image Base64",
      "type": "string"
    },
    "wait": {
      "default": true,
      "title": "Wait",
      "type": "boolean"
    },
    "project_id": {
      "default": "",
      "title": "Project Id",
      "type": "string"
    }
  },
  "title": "interior_designArguments"
}

virtual_restaging

Replace the furniture in an ALREADY-FURNISHED room with a new design style. Same workflow as virtual_staging: ask the user for the style, detect the room type from the image. Provide image_url OR image_base64.

Parameters6

image_url	string	optional
style	string	optional
space	string	optional
image_base64	string	optional
wait	boolean	optional
project_id	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "image_url": {
      "default": "",
      "title": "Image Url",
      "type": "string"
    },
    "style": {
      "default": "",
      "title": "Style",
      "type": "string"
    },
    "space": {
      "default": "",
      "title": "Space",
      "type": "string"
    },
    "image_base64": {
      "default": "",
      "title": "Image Base64",
      "type": "string"
    },
    "wait": {
      "default": true,
      "title": "Wait",
      "type": "boolean"
    },
    "project_id": {
      "default": "",
      "title": "Project Id",
      "type": "string"
    }
  },
  "title": "virtual_restagingArguments"
}

enhance_image

Enhance a photo: better lighting, sharpness and colour balance. No style needed. Provide image_url OR image_base64. area: indoor | outdoor (detect from the image). options (multi, optional): add-fire-to-fireplace, add-screen-to-tv.

Parameters6

image_url	string	optional
area	string	optional
options	any	optional
image_base64	string	optional
wait	boolean	optional
project_id	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "image_url": {
      "default": "",
      "title": "Image Url",
      "type": "string"
    },
    "area": {
      "default": "indoor",
      "title": "Area",
      "type": "string"
    },
    "options": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Options"
    },
    "image_base64": {
      "default": "",
      "title": "Image Base64",
      "type": "string"
    },
    "wait": {
      "default": true,
      "title": "Wait",
      "type": "boolean"
    },
    "project_id": {
      "default": "",
      "title": "Project Id",
      "type": "string"
    }
  },
  "title": "enhance_imageArguments"
}

remove_items

Auto-detect and remove furniture/clutter from a room photo (decluttering), leaving a clean empty space. No style needed. Provide image_url OR image_base64.

Parameters4

image_url	string	optional
image_base64	string	optional
wait	boolean	optional
project_id	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "image_url": {
      "default": "",
      "title": "Image Url",
      "type": "string"
    },
    "image_base64": {
      "default": "",
      "title": "Image Base64",
      "type": "string"
    },
    "wait": {
      "default": true,
      "title": "Wait",
      "type": "boolean"
    },
    "project_id": {
      "default": "",
      "title": "Project Id",
      "type": "string"
    }
  },
  "title": "remove_itemsArguments"
}

day_to_dusk

Convert a daytime EXTERIOR photo into a dusk / twilight scene. No style needed. Provide image_url OR image_base64. sky_style: leave empty to use the default sky (recommended — the 30+ named sky slugs are not publicly listed). options (multi, optional): shadow-removal, lawn-touch-up.

Parameters6

image_url	string	optional
sky_style	string	optional
options	any	optional
image_base64	string	optional
wait	boolean	optional
project_id	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "image_url": {
      "default": "",
      "title": "Image Url",
      "type": "string"
    },
    "sky_style": {
      "default": "",
      "title": "Sky Style",
      "type": "string"
    },
    "options": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Options"
    },
    "image_base64": {
      "default": "",
      "title": "Image Base64",
      "type": "string"
    },
    "wait": {
      "default": true,
      "title": "Wait",
      "type": "boolean"
    },
    "project_id": {
      "default": "",
      "title": "Project Id",
      "type": "string"
    }
  },
  "title": "day_to_duskArguments"
}

change_wall

Change the wall finish/colour in a room photo (AI applies a tasteful default finish). Detect `space` (room type) from the image. Provide image_url OR image_base64.

Parameters5

image_url	string	optional
space	string	optional
image_base64	string	optional
wait	boolean	optional
project_id	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "image_url": {
      "default": "",
      "title": "Image Url",
      "type": "string"
    },
    "space": {
      "default": "",
      "title": "Space",
      "type": "string"
    },
    "image_base64": {
      "default": "",
      "title": "Image Base64",
      "type": "string"
    },
    "wait": {
      "default": true,
      "title": "Wait",
      "type": "boolean"
    },
    "project_id": {
      "default": "",
      "title": "Project Id",
      "type": "string"
    }
  },
  "title": "change_wallArguments"
}

change_floor

Change the floor material in a room photo (AI applies a tasteful default material). Detect `space` from the image. Provide image_url OR image_base64.

Parameters5

image_url	string	optional
space	string	optional
image_base64	string	optional
wait	boolean	optional
project_id	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "image_url": {
      "default": "",
      "title": "Image Url",
      "type": "string"
    },
    "space": {
      "default": "",
      "title": "Space",
      "type": "string"
    },
    "image_base64": {
      "default": "",
      "title": "Image Base64",
      "type": "string"
    },
    "wait": {
      "default": true,
      "title": "Wait",
      "type": "boolean"
    },
    "project_id": {
      "default": "",
      "title": "Project Id",
      "type": "string"
    }
  },
  "title": "change_floorArguments"
}

change_ceiling

Change the ceiling finish in a room photo (AI applies a tasteful default). Detect `space` from the image. Provide image_url OR image_base64.

Parameters5

image_url	string	optional
space	string	optional
image_base64	string	optional
wait	boolean	optional
project_id	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "image_url": {
      "default": "",
      "title": "Image Url",
      "type": "string"
    },
    "space": {
      "default": "",
      "title": "Space",
      "type": "string"
    },
    "image_base64": {
      "default": "",
      "title": "Image Base64",
      "type": "string"
    },
    "wait": {
      "default": true,
      "title": "Wait",
      "type": "boolean"
    },
    "project_id": {
      "default": "",
      "title": "Project Id",
      "type": "string"
    }
  },
  "title": "change_ceilingArguments"
}

README.md10 KBView on GitHub

AI HomeDesign MCP Server — AI Virtual Staging, Home Staging & Interior Design for Claude

An open‑source Model Context Protocol (MCP) server for AI virtual staging and real‑estate photography editing. It turns the AI HomeDesign photo API into natural‑language tools, so Claude — or any MCP client — can do virtual home staging, AI interior design, photo enhancement, decluttering, and day‑to‑dusk conversions just by being asked.

What is this?

AI HomeDesign MCP Server exposes the AI HomeDesign V3 API as a set of Model Context Protocol tools over streamable HTTP. Any MCP‑compatible AI client — Claude Desktop, Claude in the browser, Cursor, and more — can then run professional real‑estate photo editing in plain English:

🛋️ Virtual staging — furnish an empty room with photorealistic AI furniture in a chosen design style. Digital home staging in seconds, with no physical furniture.
🎨 Virtual restaging & AI interior design — replace existing furniture or fully redesign a furnished room.
✨ Image enhancement — fix lighting, sharpness, and color balance for listing‑ready photos.
🧹 Item removal / decluttering — automatically remove furniture and clutter to reveal a clean space.
🌆 Day to dusk — convert a daytime exterior into a warm twilight / dusk scene.
🧱 Wall, floor & ceiling changes — restyle surfaces with a tasteful AI finish.

Because it speaks MCP, there is no SDK to learn — you describe what you want and the model calls the right tool with the right parameters.

Why virtual staging and home staging over MCP?

Traditional home staging means renting furniture and scheduling a shoot. Virtual staging for realtors replaces that with an edited photo — but it still costs hours in editing tools or days of turnaround from a staging service.

This server collapses that into a conversation: drop in a listing photo, pick a style, and get back a downloadable, market‑ready image. It's multi‑tenant (every caller uses their own AI HomeDesign key), stateless, and self‑hostable, so it fits both a single agent and a production PropTech product.

Available tools

Tool	What it does	Input
`list_capabilities`	List every tool, grouped by category	—
`list_styles`	List allowed design styles, room types & widget options	—
`describe_tool`	Show a tool's inputs + a ready‑to‑use example payload	tool slug
`virtual_staging`	Furnish an empty room in a design style	image + style + room
`virtual_restaging`	Swap furniture in an already‑furnished room	image + style + room
`interior_design`	Fully redesign a furnished room	image + style + room
`enhance_image`	Improve lighting, sharpness & color	image
`remove_items`	Declutter / remove furniture	image
`day_to_dusk`	Turn a daytime exterior into dusk	image
`change_wall` / `change_floor` / `change_ceiling`	Restyle a surface	image + room
`create_project` · `create_order` · `run_process` · `get_process` · `wait_for_result`	Low‑level primitives for full control	see `describe_tool`

Every helper accepts an image URL or a base64 image, and returns downloadable result‑image URLs.

Supported design styles: prime, modern, farmhouse, scandinavian, hampton, industrial, traditional, contemporary. Supported room types: bedroom, living‑room, kitchen, bathroom, dining‑room, home‑office, outdoor, nursery.

Quick start

Option A — Connect to the hosted server (no setup)

Get your API key. Sign in at aihomedesign.com, open API / Developer settings, and copy your x-api-key.
Generate your connector link. Paste that key into the generator at aihomedesign.com/mcp. The key is validated server‑side once, then stored encrypted; you get back a personal endpoint:
code
```
https://mcp.aihomedesign.com/aihd_<your-token>/mcp
```
Your raw key never appears in the URL.
Add it to your AI assistant. In Claude: Settings → Connectors → Add custom connector, name it AI HomeDesign, and paste the URL. Every tool shows up automatically. Works with any MCP‑compatible client.

⚠️ The connector link does not contain your raw key, but it grants access to your account — treat it like a password. Rotating your key in the AI HomeDesign dashboard revokes every link previously issued for it.

Server health check, no key needed: mcp.aihomedesign.com/health

Option B — Self‑host with Docker

bash

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

The MCP endpoint is served at http://localhost:8080/mcp (streamable HTTP), with a health check at GET /health.

Option C — Run locally with Python

bash

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

Configuration

All configuration is via environment variables — see .env.example.

Variable	Purpose	Default
`AIHD_API_KEY`	Default/fallback AI HomeDesign x‑api‑key	—
`AIHD_API_BASE`	API base URL	`https://api.aihomedesign.com/v3`
`PORT`	Listen port	`8080`
`DB_DSN`	Postgres DSN for token map + usage log (optional)	—
`TOKEN_SECRET`	Fernet key to encrypt user keys at rest (optional)	—
`MCP_CONNECTOR_BASE`	Base used to build connector links	—
`UPLOAD_DIR` / `PUBLIC_BASE`	Enable the built‑in image‑upload endpoint	—

Security & multi‑tenant design

Bring‑your‑own‑key: each request carries the caller's own AI HomeDesign key; jobs run under that key.
Keys never sit in the URL: the landing page validates a key, then mints an opaque aihd_… connector token; the raw key is stored encrypted at rest (Fernet) and swapped back in per request.
Usage logging records the tool, status, and timing per call — never the raw key (only a short, non‑reversible fingerprint).
Graceful degradation: if the database is unreachable, the server keeps serving.

How it works

code

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

The server is built on FastMCP and Starlette/uvicorn, with a pure‑ASGI auth middleware that binds the per‑request key.

Tech stack

Python 3.12 · MCP (FastMCP) · Starlette · uvicorn · httpx · PostgreSQL (optional) · Docker.

FAQ

What is an MCP server?

An MCP server exposes tools, data, and prompts to an AI model through the Model Context Protocol — an open standard introduced by Anthropic. The model discovers the available tools at runtime and calls them itself, so you never write glue code against a bespoke SDK. This repo is an MCP server whose tools happen to edit real‑estate photos.

How do you virtually stage a photo with this?

Connect the server to Claude, then send an empty‑room photo and ask for a style — for example "stage this living room in a scandinavian style." Claude calls the virtual_staging tool with the right parameters and returns a downloadable, photorealistic image. No manual editing, no design software.

Is this AI virtual staging free?

The MCP server itself is open source and MIT‑licensed, so you can self‑host it at no cost. The image processing runs on the AI HomeDesign API and uses your own API key.

Does it work with clients other than Claude?

Yes. It speaks standard MCP over streamable HTTP, so any MCP‑compatible client — Claude Desktop, Claude in the browser, Cursor, and others — can use it.

What is the difference between virtual staging and virtual restaging?

Virtual staging furnishes an empty room. Virtual restaging swaps the furniture in an already‑furnished room. Use interior_design when you want to redesign a furnished room completely rather than just replace the furniture.

Learn more

🔌 Connect in one click: aihomedesign.com/mcp
🌐 Website: aihomedesign.com
📖 Model Context Protocol: modelcontextprotocol.io

Contributing

Issues and pull requests are welcome. Please open an issue to discuss substantial changes first.

License

Released under the MIT License.

_{Keywords: MCP server · Model Context Protocol · Claude MCP · Anthropic MCP · MCP tools ·
virtual staging · AI virtual staging · virtual staging software · home staging ·
virtual staging for realtors · AI home design · AI interior design · real estate photography ·
real estate photo editing · virtual restaging · day to dusk · image enhancement ·
item removal · real estate AI · PropTech.}

Install

Tools (20)

list_capabilitieslist_stylesdescribe_toolcreate_projectlist_projectsget_projectcreate_orderget_order

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://mcp.aihomedesign.com/{connector_token}/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "aihomedesign-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.aihomedesign.com/{connector_token}/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.