Pedra

Pedra MCP 服务

面向 Pedra API 的官方 Model Context Protocol 服务——可直接在 Claude、ChatGPT、Cursor 和任何其他 MCP 客户端中使用 Pedra 的 AI 房地产照片编辑功能（虚拟布置、翻新、清空房间、增强、替换天空、移除／模糊物体、房产视频和托管式 360° 虚拟看房）。

每个 API 端点对应一个工具。每个照片和视频工具都是一次阻塞式调用，并返回最终资源 URL；无需轮询作业 ID。虚拟看房在后台生成：pedra_create_virtual_tour 会返回 tourId，随后轮询 pedra_get_virtual_tour，直到准备就绪。

快速开始

服务会从环境变量 PEDRA_API_KEY 读取你的 Pedra API 密钥（可在 Pedra 账户的 Settings 中获取）。还没有账户？无需密钥即可启动；请参阅还没有 Pedra 账户？。

服务通过 stdio 运行，并已发布到 npm，因此大多数客户端只需使用 npx 运行，无需全局安装。

Claude Desktop（一键安装）

从 Releases 下载最新的 pedra-mcp.mcpb，然后双击它（或将其拖入 Claude Desktop → Settings → Extensions）。Claude 会安装捆绑的服务，并提示你输入 PEDRA_API_KEY，无需编辑 JSON。

Claude Desktop（手动安装）

或者，将以下内容添加到你的 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

在 ~/.cursor/mcp.json（或项目中的 .cursor/mcp.json）里：

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

任何 MCP 客户端

在环境中设置密钥后，直接运行二进制文件：

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

或者安装它：

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

Smithery

你也可以通过 Smithery 自动安装并配置 Pedra：

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

（将 claude 替换为 cursor、windsurf 等。）Smithery 会提示你输入 PEDRA_API_KEY，并为你写入客户端配置。

还没有 Pedra 账户？

无需设置 PEDRA_API_KEY 即可启动服务，例如在 Claude Code 中：

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

然后只需提出需求（例如“用 Pedra 布置这张照片”）。没有密钥时，服务会添加两个工具，其余操作由助手完成：

1. 使用你的电子邮箱调用 pedra_request_access。Pedra 会向你发送一个链接（有效期为 30 分钟）：新账户可在链接中设置密码，已有账户点击 Allow。在你点击之前不会创建任何内容，而且你可以拒绝。
2. 持续调用 pedra_check_access，直到你完成确认。批准后，本次会话中的所有 Pedra 工具都可使用。密钥仅保存在内存中，绝不会写入磁盘；工具结果会显示密钥以及如何保存：将其作为 PEDRA_API_KEY 添加到服务的 env 中（例如 claude mcp add pedra -e PEDRA_API_KEY=<key> -- npx -y @pedra-ai/mcp），或将其粘贴到 Claude Desktop 扩展的设置中。

在此之前，其他工具会回复“No API key yet: call pedra_request_access with the user's email”。必须确认收件箱，不接受一次性邮箱域名，并且请求会受到频率限制。新账户会获得 Pedra 的免费试用额度。

（在 ChatGPT 和 claude.ai 中，请改用 Pedra 托管的连接器：连接后会进行登录，新用户可在其中创建账户。）

工具

九种图像编辑工具（从增强到模糊）还接受 propertyId，用于将结果保存到该房产的图库中；也接受 name，用于在同一次调用中将原始照片以该名称保存到图库中。结果随后会包含原始照片的 source（imageId、name）。preserveAspectRatio 会让结果保持与输入完全相同的尺寸。

工具	端点	功能
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	将房产照片（或使用 type: "360" 时的 360° 照片）以 URL 形式列出
pedra_create_property	/create_property	创建房产
pedra_add_images_to_property	/add_images_to_property	通过 URL 向房产添加照片（或使用 type: "360" 添加 360° 照片），可选提供 names
pedra_add_local_panoramas	/add_images_to_property (batched)	**仅限本地：**将此电脑上的 360° 照片文件上传到房产
pedra_create_upload_link	/create_upload_link	无需登录的页面，可从手机或电脑上传照片或 360° 照片（仅限全景游览使用 type: "360"）
pedra_create_virtual_tour	/create_virtual_tour	创建托管的 360° 虚拟游览（AI 为房间命名并建立链接）
pedra_get_virtual_tour	/get_virtual_tour	获取游览状态、分享链接、嵌入代码、场景和链接
pedra_list_virtual_tours	/list_virtual_tours	列出账户中的虚拟游览
pedra_update_virtual_tour	/update_virtual_tour	重命名、重新排序、移除房间、重新建立链接、更改样式（免费）
pedra_add_virtual_tour_scenes	/add_virtual_tour_scenes	在游览末尾添加房间
pedra_credits	/credits	查看套餐和剩余点数
pedra_feedback	/feedback	点赞或点踩，可选返还点数
pedra_request_access	/agent_signup	**仅限未提供 API 密钥时：**向用户发送创建账户或授权账户的链接
pedra_check_access	/agent_signup_status	**仅限未提供 API 密钥时：**检查申请状态；获批后，本次会话中的所有工具均可使用

大多数图像工具都接受 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_create_upload_link 上传：用户可在无需登录的页面上传（最多 100 个文件，有效期 24 h），然后 pedra_list_property_images 会返回这些照片的 URL，供编辑、pedra_create_video 或 pedra_create_virtual_tour 使用。

每日上传量有限制：免费计划可上传 30 张图像，付费计划可上传 500 张（于 UTC 午夜重置）；统计所有从应用外部存储的图像（pedra_add_images_to_property、pedra_add_local_panoramas、导览中的 URL 场景、上传链接文件）。超出限制后，调用会失败并返回 HTTP 429, upload_limit，且不会存储任何内容。上传链接：免费计划每天 5 个，付费计划每天 50 个（upload_link_limit）。

连接后可使用的提示词示例：

“使用 Pedra 将 https://example.com/empty-living-room.jpg 虚拟布置成极简风格的客厅。”

“将 /Users/me/Desktop/empty-living-room.jpg 虚拟布置成极简风格的客厅。”

“我还剩多少 Pedra 积分？”

虚拟导览

提交 360° 照片，即可获得托管、关联且可分享的虚拟导览：AI 会为房间命名，并放置房间之间的导航点。导览工具的名称、描述和输入架构与 Pedra 托管的 MCP 服务（https://app.pedra.ai/mcp）相同，因此 Agent 在两者上的行为一致。

典型流程：

1. 将 360° 照片添加到房产中。
   • 此计算机上的文件 → 使用 pedra_add_local_panoramas，并按行走顺序传入路径。此工具仅在此本地服务中提供：它会从磁盘读取文件并以 base64 编码发送，每次调用最多 10 个文件，且受 API 的 50 MB 请求限制。超过约 33 MB 的文件无法通过此方式发送。
   • 某人手机上的照片（或大型文件） → 使用 pedra_create_upload_link 并设置 type: "360"，然后将 uploadUrl 提供给对方（无需登录，有效期 24 h）。
   • 已在线的照片 → 跳过此步骤，将 URL 作为 scenes 传入。
2. **创建：**使用 pedra_create_virtual_tour，传入 propertyId（使用按上传顺序排列的所有 360° 照片）或传入 scenes。它会立即返回 tourId。
3. **等待：**轮询 pedra_get_virtual_tour，直到 status 为 "ready"（每个房间约需 10 s）；然后分享 tourUrl 或嵌入 embedCode。如果创建失败，状态为 "failed"，并会说明原因，且不收费。
4. 使用 pedra_update_virtual_tour 调整（免费、即时），或使用 pedra_add_virtual_tour_scenes 追加房间。

链接收费规则："sequential"（默认；每个房间连接到下一个）收费 max(3, ceil(rooms/3)) 个积分；"smart"（由 AI 确定房间之间的连接方式）收费 5–160 个积分；"none" 不收费。删除导览只能通过 API 操作（未作为工具提供）。

“为 Calle Mayor 12 创建 Pedra 虚拟导览，使用 /Users/me/360/entrance.jpg、/Users/me/360/living.jpg 和 /Users/me/360/kitchen.jpg，按此顺序排列，并把链接发给我。”

工作原理

此服务是 @pedra-ai/sdk 的轻量封装，由该 SDK 编码处理 API 的契约细节：

• 默认采用同步方式（虚拟导览除外）。 每个照片和视频端点都会阻塞，直到在响应正文中返回最终 URL。即使是 pedra_create_video，也会在服务端轮询，并在响应中直接返回已完成的 videoUrl（可能需要约 10 分钟；API 会通过心跳保持连接）。
• 错误会作为工具错误返回。 API 的 4xx 响应（积分不足、图像无效等）会作为带有易读消息的 MCP 工具错误返回，而不是导致崩溃。

隐私政策

此服务会将你传入的图片／视频 URL 和参数发送到 Pedra API，以执行你请求的编辑，并使用你的 PEDRA_API_KEY 进行身份验证。如果没有密钥，pedra_request_access 会将你提供的电子邮件地址发送给 Pedra，以便 Pedra 向你发送确认链接；通过这种方式获取的密钥仅在当前会话期间保存在内存中。此服务本身不存储任何数据。数据收集、使用、存储、保留、与第三方共享以及联系信息均由 Pedra 的隐私政策说明：**https://pedra.ai/privacy**。

许可证

MIT © Pedra