Content
# Pedra MCP Server
Official [Model Context Protocol](https://modelcontextprotocol.io) server for the [Pedra API](https://pedra.ai/api-documentation) — use Pedra's AI real-estate photo editing (virtual staging, renovation, room emptying, enhancement, sky replacement, object removal/blur, and property videos) directly from **Claude, ChatGPT, Cursor**, and any other MCP client.
[](https://www.npmjs.com/package/@pedra-ai/mcp)
[](https://registry.modelcontextprotocol.io)
[](cursor://anysphere.cursor-deeplink/mcp/install?name=pedra&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBwZWRyYS1haS9tY3AiXSwiZW52Ijp7IlBFRFJBX0FQSV9LRVkiOiJZT1VSX1BFRFJBX0FQSV9LRVkifX0=)
It exposes **one tool per API endpoint**. Each tool is a single blocking call that returns the final asset URL(s) — there are no job IDs to poll.
## Quick start
You need a Pedra API key — get one from your [Pedra account](https://app.pedra.ai). The server reads it from the `PEDRA_API_KEY` environment variable.
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](https://github.com/pedra-ai/pedra-mcp/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):
```json
{
"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):
```json
{
"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:
```bash
PEDRA_API_KEY=your-api-key npx -y @pedra-ai/mcp
```
Or install it:
```bash
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](https://smithery.ai/server/@pedra-ai/mcp):
```bash
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.
## 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 |
| `pedra_list_properties` | `/list_properties` | List the account's properties |
| `pedra_list_property_images` | `/list_property_images` | List a property's photos as URLs |
| `pedra_create_property` | `/create_property` | Create a property |
| `pedra_add_images_to_property` | `/add_images_to_property` | Add photos to a property by URL |
| `pedra_credits` | `/credits` | Read plan + remaining credits |
| `pedra_feedback` | `/feedback` | Thumbs up/down + optional credit-back |
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.
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?"
## How it works
This server is a thin wrapper over [`@pedra-ai/sdk`](https://www.npmjs.com/package/@pedra-ai/sdk), which encodes the API's contract details:
- **Synchronous by design.** Every 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](https://pedra.ai) to perform the requested edit, authenticated with your `PEDRA_API_KEY`. 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
