{
  "markdown": "# reel-estate-mcp\n\n**Turn real-estate listing photos into cinematic property videos from your AI\nassistant.** `reel-estate-mcp` is a [Model Context Protocol](https://modelcontextprotocol.io)\n(MCP) server that connects **Claude, Cursor, and other AI assistants** to your\n[**Reel Estate**](https://tryreelestate.com) account — so you can generate motion\nclips, AI-edit photos (virtual staging, twilight, seasonal), add voiceover, and\nrender finished listing videos, all in plain language.\n\n> Reel Estate is the AI real-estate video platform that turns property photos into\n> scroll-stopping listing videos. Create a free account at\n> **[tryreelestate.com](https://tryreelestate.com)**.\n\nYou sign in once through your browser (OAuth + PKCE — **no API keys, no secrets**),\nand every call is proxied through the backend's `/mcp` endpoint, which stays the\nsingle authority for auth, plans, and permissions. This bridge's one superpower on\ntop of that: it can read **local image files** and stream them straight into a\nproject — something a purely remote server can't do.\n\n- 🎬 **Generate real-estate videos** — animate photos into clips, then render the movie\n- 🖼️ **AI photo editing** — virtual staging, twilight, upscale, seasonal, replace/remove/add\n- 🎙️ **Voiceover & timeline** — narration, music, overlays, reordering\n- 📤 **Local uploads** — push photos from disk into a project\n- 🔐 **Browser sign-in** — public OAuth client + PKCE; nothing secret stored\n- 🤖 **Works with** Claude Code, Claude Desktop, and Cursor\n\n## Requirements\n\n- **Node.js 18+**\n- A **[Reel Estate](https://tryreelestate.com) account** (a **paid plan** is\n  required to create/generate/render; free accounts are read-only over the MCP)\n- An MCP-compatible client: **Claude Code**, **Claude Desktop**, or **Cursor**\n\n## Install\n\nNothing to clone or build — your MCP client launches it on demand via `npx`. You\nonly need **Node.js ≥ 18**. (Prefer a global command? `npm install -g reel-estate-mcp`,\nthen use `reel-estate-mcp` in place of `npx -y reel-estate-mcp` below.)\n\n## Connect your assistant\n\n**Zero config** — the bridge connects to Reel Estate and handles browser sign-in\nfor you. There's nothing to set up.\n\n### Claude Code\n\n```bash\nclaude mcp add reel-estate -- npx -y reel-estate-mcp\n```\n\n### Claude Desktop / Cursor\n\nAdd to your client's MCP config (`claude_desktop_config.json`, `~/.cursor/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"reel-estate\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"reel-estate-mcp\"]\n    }\n  }\n}\n```\n\n## First run — sign in\n\nThe first tool call opens your browser to sign in with your Reel Estate account\n(Clerk OAuth, authorization code + PKCE). After you approve, the browser returns to\n`http://localhost:8765/callback`, tokens cache under `~/.reel-estate-mcp`, and\nyou're in — you won't log in again until the token expires.\n\nStart with **`whoami`** to confirm auth and see your plan, then just ask:\n\n- *\"List my recent projects.\"*\n- *\"Create a project for 123 Main St and upload the photos in ./listing.\"*\n- *\"Virtually stage the living room photo, generate a drone clip, then render in 9:16.\"*\n- *\"How many credits and exports do I have left?\"*\n\nTo switch users or re-authorize, run **`logout`** (revokes server-side + clears\nthe cache) or delete `~/.reel-estate-mcp`.\n\n## Tools\n\nAll API tools proxy through the backend's `/mcp` `api_request`, so the backend's\nown authorization and plan rules apply.\n\n| Tool | What it does |\n| --- | --- |\n| `help` | Guided, always-current walkthrough (also the `getting_started` prompt) |\n| `whoami` | Confirm auth; reports `plan`, `canWrite`, and a `writeAccess` reason. **Run first.** |\n| `login` / `logout` | Start browser sign-in / clear the session (server revoke + local cache) |\n| `list_projects` · `get_project` · `project_stats` | Browse projects |\n| `list_clips` · `list_movies` · `list_voices` | Browse clips, rendered movies, TTS voices |\n| `resolve_address` | Geocode a free-text address → ranked candidates (for real-listing projects) |\n| `add_image_from_file` | Upload a **local** image into a project (presigned upload — no storage creds) |\n| `generate_clip` · `get_clip_status` | Animate a photo into a video clip (Runway); poll the job |\n| `edit_image` | AI photo edit — virtual staging, twilight, upscale, seasonal, replace/remove/add, manual |\n| `add_timeline_audio` · `add_timeline_overlay` | Place voiceover/music/audio or an image/text overlay |\n| `move_timeline_element` · `reorder_timeline` | Retime / resequence the timeline |\n| `render_movie` | Assemble the timeline into the final listing video |\n| `list_endpoints` · `api_request` | Discover the API catalog / call any route — the escape hatch |\n\n### Paid vs free\n\nWrites and generation over the MCP require a **paid plan** — free accounts are\n**read-only** (browse projects, clips, and movies). `whoami` reports this up front;\na blocked write returns `403 MCP_PAID_PLAN_REQUIRED`. See plans at\n[tryreelestate.com](https://tryreelestate.com).\n\n## How auth works\n\n```\nfirst tool call\n   │   StreamableHTTP client ──► backend /mcp  (401, needs auth)\n   ▼\nopens your browser ──► Clerk OAuth (authorization code + PKCE, public client)\n   │                                                   │\n   ▼                                                   ▼\nloopback http://localhost:8765/callback?code=…   access + refresh tokens\n   │                                                   │\n   └────────────► finishAuth(code) ──► tokens cached ──┘  (~/.reel-estate-mcp)\n\nevery later call:  callTool(\"api_request\", …) over the authed /mcp connection\n```\n\n- **No secrets to distribute** — public client + PKCE, browser login per user.\n- **Prod-capable** — uses the same OAuth the backend serves at `/mcp`.\n- **The backend is the single auth authority** — this bridge never mints tokens.\n\n## Troubleshooting\n\n| Problem | Fix |\n| --- | --- |\n| No login prompt / \"not authenticated\" | Run any tool (or `login`), open the printed URL, and approve. |\n| Switch accounts / re-authorize | Run `logout`, or delete `~/.reel-estate-mcp`. |\n| Writes blocked (`403 MCP_PAID_PLAN_REQUIRED`) | Creating/generating/rendering needs a paid plan; free accounts are read-only. See [tryreelestate.com](https://tryreelestate.com). |\n\n## Architecture\n\n- **`src/config.ts`** — validated env (loaded from this package's folder); derives\n  the `/mcp` URL, OAuth store dir, callback port, read-only flag, and default client id.\n- **`src/oauth.ts`** — `OAuthClientProvider`: uses the public `client_id`, caches\n  tokens + the PKCE verifier, opens the system browser.\n- **`src/upstream.ts`** — the single OAuth'd MCP client connection to `/mcp` (with\n  the loopback callback server); `callTool` / `callApiRequest` proxies.\n- **`src/api-client.ts`** — `ApiClient` over `callApiRequest`; enforces read-only.\n- **`src/catalog.ts`** — the endpoint catalog surfaced by `list_endpoints`.\n- **`src/tools.ts`** — tools as plain functions (smoke-testable).\n- **`src/index.ts`** — registers the tools as MCP tools over **stdio**.\n\n### Adding a tool\n\n1. Add `async function fooBar(api, args)` in `src/tools.ts` (use `api.get(...)` /\n   `api.request(...)`, which proxy through `/mcp`).\n2. Register it in `src/index.ts` with a Zod `inputSchema`.\n3. Add it to `scripts/smoke.ts` if it's a GET.\n\nEverything is already reachable through `api_request`; convenience tools just make\nthe common paths first-class.\n\n## About Reel Estate\n\n[**Reel Estate**](https://tryreelestate.com) helps real-estate agents and marketers\nturn ordinary **listing photos into professional property videos** — AI virtual\nstaging, twilight conversion, motion/drone clips, voiceover narration, and one-click\nrendering for Instagram, TikTok, and YouTube. This MCP server brings that workflow\ninto your AI assistant. **[Get started at tryreelestate.com →](https://tryreelestate.com)**\n\n---\n\n*Keywords: real estate video generator, AI listing video, virtual staging, MCP\nserver, Model Context Protocol, Claude, Cursor, property video marketing, drone\nreal estate video, twilight photo editing.*\n",
  "bytes": 8041,
  "sha": "36b31e476d2ffdd3a36b0104ce0026855f6cff5976f99431c1ef4746f4c42765",
  "repo_slug": "tryreelestate/reel-estate-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_tryreelestate_reel_estate_mcp_e07e8f92/readme"
}