内容
# Pedra MCP 服务器
Pedra API 的官方 [模型上下文协议](https://modelcontextprotocol.io) 服务器 — 直接从 **Claude, ChatGPT, Cursor** 和任何其他 MCP 客户端使用 Pedra 的 AI 房地产照片编辑（虚拟装修、房间清空、增强、天空替换、物体移除/模糊和房产视频）。
[](https://www.npmjs.com/package/@pedra-ai/mcp)
[](https://registry.modelcontextprotocol.io)
[](cursor://anysphere.cursor-deeplink/mcp/install?name=pedra&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBwZWRyYS1haS9tY3AiXSwiZW52Ijp7IlBFRFJBX0FQSV9LRVkiOiJZT1VSX1BFRFJBX0FQSV9LRVkifX0=)
它暴露 **一个工具对应一个 API 端点**。每个工具都是一个单独的阻塞调用，返回最终的资产 URL(s) — 没有作业 ID 需要轮询。
## 快速开始
您需要一个 Pedra API 密钥 — 从您的 [Pedra 账户](https://app.pedra.ai) 获取。服务器从 `PEDRA_API_KEY` 环境变量中读取它。
服务器运行在标准输入/输出上，并发布到 npm，因此大多数客户端只需使用 `npx` 运行 — 无需全局安装。
### Claude Desktop（一步到位）
下载最新的 **`pedra-mcp.mcpb`** 从 [Releases](https://github.com/pedra-ai/pedra-mcp/releases) 并双击它（或拖入 Claude Desktop → 设置 → 扩展）。Claude 安装捆绑的服务器并提示输入您的 `PEDRA_API_KEY` — 无需编辑 JSON。
### Claude Desktop（手动）
或将以下内容添加到您的 `claude_desktop_config.json`（设置 → 开发者 → 编辑配置）：
```json
{
"mcpServers": {
"pedra": {
"command": "npx",
"args": ["-y", "@pedra-ai/mcp"],
"env": { "PEDRA_API_KEY": "您的 API 密钥" }
}
}
}
```
### Cursor
在 `~/.cursor/mcp.json`（或项目中的 `.cursor/mcp.json`）：
```json
{
"mcpServers": {
"pedra": {
"command": "npx",
"args": ["-y", "@pedra-ai/mcp"],
"env": { "PEDRA_API_KEY": "您的 API 密钥" }
}
}
}
```
### 任意 MCP 客户端
直接使用环境中的密钥运行二进制文件：
```bash
PEDRA_API_KEY=您的 API 密钥 npx -y @pedra-ai/mcp
```
或安装它：
```bash
npm install -g @pedra-ai/mcp
PEDRA_API_KEY=您的 API 密钥 pedra-mcp
```
### Smithery
您还可以通过 [Smithery](https://smithery.ai/server/@pedra-ai/mcp) 自动安装和配置 Pedra：
```bash
npx -y @smithery/cli install @pedra-ai/mcp --client claude
```
（将 `claude` 替换为 `cursor`、`windsurf` 等。）Smithery 提示输入您的 `PEDRA_API_KEY` 并为您编写客户端配置。
## 工具
| 工具 | 端点 | 功能 |
|------|----------|--------------|
| `pedra_enhance` | `/enhance` | 改善照明、颜色、锐度 |
| `pedra_enhance_and_correct_perspective` | `/enhance_and_correct_perspective` | 增强 + 纠正视角 |
| `pedra_empty_room` | `/empty_room` | 移除所有家具/物体 |
| `pedra_furnish` | `/furnish` | 虚拟装修房间 |
| `pedra_renovation` | `/renovation` | 装修墙壁/地板/饰面 |
| `pedra_edit_via_prompt` | `/edit_via_prompt` | 根据自然语言提示编辑 |
| `pedra_sky_blue` | `/sky_blue` | 替换为晴朗的蓝色天空 |
| `pedra_remove_object` | `/remove_object` | 使用遮罩移除物体 |
| `pedra_blur` | `/blur` | 模糊面部、车牌等 |
| `pedra_create_video` | `/create_video` | 从图像渲染房产视频 |
| `pedra_update_video` | `/update_video` | 编辑视频而无需重新渲染未更改的剪辑 |
| `pedra_generate_voice_script` | `/generate_voice_script` | 从房产照片编写旁白脚本 |
| `pedra_generate_voice` | `/generate_voice` | 将脚本转换为旁白音频轨道 |
| `pedra_music_library` | `/music_library` | 列出背景音乐曲目 + 语音语言 |
| `pedra_list_properties` | `/list_properties` | 列出账户的房产 |
| `pedra_list_property_images` | `/list_property_images` | 列出房产的照片 URL |
| `pedra_create_property` | `/create_property` | 创建房产 |
| `pedra_add_images_to_property` | `/add_images_to_property` | 通过 URL 将照片添加到房产 |
| `pedra_credits` | `/credits` | 读取计划 + 剩余积分 |
| `pedra_feedback` | `/feedback` | 点赞/点踩 + 可选的积分返还 |
大多数图像工具接受 `imageUrl` 加上几个可选参数；请在您的 MCP 客户端中查看每个工具的输入模式。`imageUrl`（和 `maskUrl`，以及每个 `create_video` 帧）接受以下任意：
- 公共 `https://` URL，
- `data:` URI，或
- **本地图像文件的绝对路径** — 服务器读取它并将其内联为 base64，以便您可以在不首先托管的情况下将工具指向您刚刚拖入的文件（`.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`, `.bmp`, `.tif/.tiff`, `.heic/.heif`, `.avif`；最多 40 MB）。
> 注意：**粘贴到聊天中的图像** 不是文件路径，因此无法转发到工具 — 拖入文件，或保存粘贴并传递其路径。
连接后示例提示：
> “使用 Pedra 将 https://example.com/empty-living-room.jpg 虚拟装修为极简主义客厅。”
> “将 /Users/me/Desktop/empty-living-room.jpg 虚拟装修为极简主义客厅。”
> “我还剩多少 Pedra 积分？”
## 工作原理
该服务器是 [`@pedra-ai/sdk`](https://www.npmjs.com/package/@pedra-ai/sdk) 的薄封装，它编码了 API 的契约细节：
- **设计为同步。** 每个端点阻塞并在响应正文中返回最终 URL(s)。即使 `pedra_create_video` 也会轮询服务器端并内联返回已完成的 `videoUrl`（最多约 10 分钟；API 通过心跳保持连接活动）。
- **错误是工具错误。** API 的 4xx 响应（积分不足、图像错误等）作为 MCP 工具错误返回，附带可读消息，而不是崩溃。
## 隐私政策
此服务器将您传递的图像/视频 URL 和参数发送到 [Pedra API](https://pedra.ai) 以执行请求的编辑，并使用您的 `PEDRA_API_KEY` 进行身份验证。它本身不存储任何数据。数据收集、使用、存储、保留、第三方共享和联系信息均受 Pedra 的隐私政策约束：**https://pedra.ai/privacy**。
## 许可证
MIT © Pedra
