Pedra

Pedra MCP Server

Official Model Context Protocol server for the Pedra API — use Pedra's AI real-estate photo editing (virtual staging, renovation, room emptying, enhancement, sky replacement, object removal/blur, property videos, and hosted 360° virtual tours) directly from Claude, ChatGPT, Cursor, and any other MCP client.

It exposes one tool per API endpoint. Each photo and video tool is a single blocking call that returns the final asset URL(s) — there are no job IDs to poll. Virtual tours build in the background: pedra_create_virtual_tour returns a tourId, and pedra_get_virtual_tour is polled until it's ready.

Quick start

The server reads your Pedra API key (Settings in your Pedra account) from the PEDRA_API_KEY environment variable. No account yet? Start it without a key — see No Pedra account yet?.

The server runs over stdio and is published to npm, so most clients just run it with npx — no global install needed.

Claude Desktop (one-click)

Download the latest pedra-mcp.mcpb from Releases and double-click it (or drag it into Claude Desktop → Settings → Extensions). Claude installs the bundled server and prompts for your PEDRA_API_KEY — no JSON editing.

Claude Desktop (manual)

Or add this to your claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "pedra": {
      "command": "npx",
      "args": ["-y", "@pedra-ai/mcp"],
      "env": { "PEDRA_API_KEY": "your-api-key" }
    }
  }
}

Cursor

In ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "pedra": {
      "command": "npx",
      "args": ["-y", "@pedra-ai/mcp"],
      "env": { "PEDRA_API_KEY": "your-api-key" }
    }
  }
}

Any MCP client

Run the binary directly with the key in the environment:

PEDRA_API_KEY=your-api-key npx -y @pedra-ai/mcp

Or install it:

npm install -g @pedra-ai/mcp
PEDRA_API_KEY=your-api-key pedra-mcp

Smithery

You can also install and configure Pedra automatically via Smithery:

npx -y @smithery/cli install @pedra-ai/mcp --client claude

(swap claude for cursor, windsurf, etc.) Smithery prompts for your PEDRA_API_KEY and writes the client config for you.

No Pedra account yet?

Start the server without PEDRA_API_KEY, for example in Claude Code:

claude mcp add pedra -- npx -y @pedra-ai/mcp

Then just ask for something ("stage this photo with Pedra"). Without a key the server adds two tools, and the assistant does the rest:

1. pedra_request_access with your email. Pedra emails you a link (valid 30 minutes): a new account chooses a password there, an existing one clicks Allow. Nothing is created until you click, and you can decline.
2. pedra_check_access until you've confirmed. Once approved, every Pedra tool works for the rest of the session. The key is kept in memory only, never written to disk; the tool result shows it along with how to keep it: add it as PEDRA_API_KEY to the server's env (e.g. claude mcp add pedra -e PEDRA_API_KEY=<key> -- npx -y @pedra-ai/mcp, or paste it into the extension's settings in Claude Desktop).

Until then, the other tools answer "No API key yet: call pedra_request_access with the user's email". Inbox confirmation is required, disposable email domains are refused, and requests are rate-limited. New accounts start with Pedra's free trial credits.

(In ChatGPT and claude.ai, use Pedra's hosted connector instead: connecting it runs a sign-in where new users can create an account.)

Tools

Tool	Endpoint	What it does
pedra_enhance	/enhance	Improve lighting, color, sharpness
pedra_enhance_and_correct_perspective	/enhance_and_correct_perspective	Enhance + straighten perspective
pedra_empty_room	/empty_room	Remove all furniture/objects
pedra_furnish	/furnish	Virtually stage a room
pedra_renovation	/renovation	Renovate walls/floors/finishes
pedra_edit_via_prompt	/edit_via_prompt	Edit from a natural-language prompt
pedra_sky_blue	/sky_blue	Replace a dull sky with clear blue
pedra_remove_object	/remove_object	Remove an object using a mask
pedra_blur	/blur	Blur faces, license plates, etc.
pedra_create_video	/create_video	Render a property video from images
pedra_update_video	/update_video	Edit a video without re-rendering unchanged clips
pedra_generate_voice_script	/generate_voice_script	Write a voiceover script from property photos
pedra_generate_voice	/generate_voice	Turn a script into a voiceover audio track
pedra_music_library	/music_library	List background-music tracks, voice languages + narration voices
pedra_list_properties	/list_properties	List the account's properties
pedra_list_property_images	/list_property_images	List a property's photos (or, with type: "360", its 360° photos) as URLs
pedra_create_property	/create_property	Create a property
pedra_add_images_to_property	/add_images_to_property	Add photos (or, with type: "360", 360° photos) to a property by URL
pedra_add_local_panoramas	/add_images_to_property (batched)	Local only: upload 360° photo files from this computer into a property
pedra_create_upload_link	/create_upload_link	No-login page to upload photos or 360° photos from a phone or computer (type: "360" for tours only)
pedra_create_virtual_tour	/create_virtual_tour	Build a hosted 360° virtual tour (AI names and links the rooms)
pedra_get_virtual_tour	/get_virtual_tour	Tour status, share link, embed code, scenes, links
pedra_list_virtual_tours	/list_virtual_tours	List the account's virtual tours
pedra_update_virtual_tour	/update_virtual_tour	Rename, reorder, remove rooms, re-link, restyle (free)
pedra_add_virtual_tour_scenes	/add_virtual_tour_scenes	Add rooms to the end of a tour
pedra_credits	/credits	Read plan + remaining credits
pedra_feedback	/feedback	Thumbs up/down + optional credit-back
pedra_request_access	/agent_signup	Only without an API key: email the user a link to create/allow their account
pedra_check_access	/agent_signup_status	Only without an API key: check the request; once approved, every tool works for the session

Most image tools take an imageUrl plus a few optional parameters; see each tool's input schema in your MCP client. The imageUrl (and maskUrl, and each create_video frame) accepts any of:

• a public https:// URL,
• a data: URI, or
• an absolute path to a local image file — the server reads it off disk and inlines it as base64 for you, so you can point a tool at a file you just dragged in without hosting it first (.jpg, .jpeg, .png, .webp, .gif, .bmp, .tif/.tiff, .heic/.heif, .avif; up to 40 MB).

Note: an image pasted into the chat is not a file path, so it can't be forwarded to the tool — drag in a file, or save the paste and pass its path. Photos on the user's phone go through pedra_create_upload_link: they upload on a no-login page (up to 100 files, 24 h), then pedra_list_property_images returns their URLs for editing, pedra_create_video or pedra_create_virtual_tour.

Uploads are limited per day: 30 images on the free plan, 500 on paid plans (reset at midnight UTC), counting every image stored from outside the app (pedra_add_images_to_property, pedra_add_local_panoramas, URL scenes in tours, upload-link files); over it the call fails with HTTP 429, upload_limit and nothing is stored. Upload links: 5 a day free, 50 paid (upload_link_limit).

Example prompts once connected:

"Use Pedra to virtually stage https://example.com/empty-living-room.jpg as a minimalist living room."

"Virtually stage /Users/me/Desktop/empty-living-room.jpg as a minimalist living room."

"How many Pedra credits do I have left?"

Virtual tours

POST your 360° photos, get back a hosted, linked, shareable virtual tour: AI names the rooms and places the door-to-door navigation points. The tour tools have the same names, descriptions and input schemas as Pedra's hosted MCP server (https://app.pedra.ai/mcp), so an agent behaves the same on either.

A typical flow:

1. Get the 360° photos into a property.
   • Files on this computer → pedra_add_local_panoramas with the paths in walking order. This tool exists only in this local server: it reads the files off disk and sends them base64-encoded, 10 per call under the API's 50 MB request limit. Files over ~33 MB can't go this way.
   • Photos on someone's phone (or big files) → pedra_create_upload_link with type: "360", and hand over the uploadUrl (no login, valid 24 h).
   • Photos already online → skip this step and pass the URLs as scenes.
2. Build it: pedra_create_virtual_tour with the propertyId (uses every 360° photo in upload order) or with scenes. It returns a tourId straight away.
3. Wait: poll pedra_get_virtual_tour until status is "ready" (about 10 s per room) — then share tourUrl or embed embedCode. A "failed" build says why and costs nothing.
4. Adjust with pedra_update_virtual_tour (free, instant) or append rooms with pedra_add_virtual_tour_scenes.

Linking costs max(3, ceil(rooms/3)) credits for "sequential" (default; each room to the next), 5–160 for "smart" (AI works out which rooms connect), and nothing for "none". Deleting a tour is API-only (not exposed as a tool).

"Make a Pedra virtual tour of Calle Mayor 12 from /Users/me/360/entrance.jpg, /Users/me/360/living.jpg and /Users/me/360/kitchen.jpg, in that order, and give me the link."

How it works

This server is a thin wrapper over @pedra-ai/sdk, which encodes the API's contract details:

• Synchronous by design (except virtual tours). Every photo and video endpoint blocks and returns the final URL(s) in the response body. Even pedra_create_video polls server-side and returns the finished videoUrl inline (it can take up to ~10 minutes; the API keeps the connection alive with a heartbeat).
• Errors are tool errors. The API's 4xx responses (insufficient credits, bad image, …) come back as MCP tool errors with a readable message, not crashes.

Privacy Policy

This server sends the image/video URLs and parameters you pass to the Pedra API to perform the requested edit, authenticated with your PEDRA_API_KEY. Without a key, pedra_request_access sends the email address you give it to Pedra so Pedra can email you a confirmation link; a key obtained that way is held in memory for the session only. It stores no data itself. Data collection, usage, storage, retention, third-party sharing, and contact information are covered by Pedra's privacy policy: https://pedra.ai/privacy.

License

MIT © Pedra