Pedra

Edição de fotos e vídeos imobiliários com IA — staging virtual, reforma, esvaziamento de ambientes, aprimoramento, substituição de céu, remoção de objetos e vídeos de imóveis — via API Pedra.

GitHub

Documentação

Servidor MCP Pedra

Servidor oficial do Model Context Protocol para a API Pedra — use a edição de fotos de imóveis com IA da Pedra (ambientação virtual, reforma, esvaziamento de ambientes, melhoria, substituição de céu, remoção/desfoque de objetos, vídeos de propriedades e tours virtuais 360° hospedados) diretamente do Claude, ChatGPT, Cursor e qualquer outro cliente MCP.

Ele expõe uma ferramenta por endpoint da API. Cada ferramenta de foto e vídeo é uma única chamada bloqueante que retorna o(s) URL(s) final(is) do ativo — não há IDs de tarefa para consultar. Os tours virtuais são construídos em segundo plano: pedra_create_virtual_tour retorna um tourId, e pedra_get_virtual_tour é consultado até ficar pronto.

Início rápido

O servidor lê sua chave da API Pedra (Configurações na sua conta Pedra) da variável de ambiente PEDRA_API_KEY. Ainda não tem conta? Inicie sem chave — veja Ainda não tem conta Pedra?.

O servidor roda via stdio e é publicado no npm, então a maioria dos clientes apenas o executa com npx — sem necessidade de instalação global.

Claude Desktop (um clique)

Baixe o pedra-mcp.mcpb mais recente de Releases e clique duas vezes nele (ou arraste-o para Claude Desktop → Configurações → Extensões). O Claude instala o servidor incluído e solicita seu PEDRA_API_KEY — sem edição de JSON.

Claude Desktop (manual)

Ou adicione isto ao seu claude_desktop_config.json (Configurações → Desenvolvedor → Editar Config):

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

Cursor

Em ~/.cursor/mcp.json (ou .cursor/mcp.json em um projeto):

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

Qualquer cliente MCP

Execute o binário diretamente com a chave no ambiente:

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

Ou instale-o:

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

Smithery

Você também pode instalar e configurar a Pedra automaticamente via Smithery:

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

(troque claude por cursor, windsurf, etc.) O Smithery solicita seu PEDRA_API_KEY e escreve a configuração do cliente para você.

Ainda não tem conta Pedra?

Inicie o servidor sem PEDRA_API_KEY, por exemplo no Claude Code:

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

Depois é só pedir algo ("faça a ambientação desta foto com a Pedra"). Sem chave, o servidor adiciona duas ferramentas, e o assistente faz o resto:

pedra_request_access com seu e-mail. A Pedra envia um link por e-mail (válido por 30 minutos): uma conta nova escolhe uma senha lá, uma conta existente clica em Permitir. Nada é criado até você clicar, e você pode recusar.
pedra_check_access até você confirmar. Depois de aprovado, todas as ferramentas da Pedra funcionam pelo restante da sessão. A chave é mantida apenas em memória, nunca gravada em disco; o resultado da ferramenta a mostra junto com como mantê-la: adicione-a como PEDRA_API_KEY ao env do servidor (ex.: claude mcp add pedra -e PEDRA_API_KEY=<key> -- npx -y @pedra-ai/mcp, ou cole-a nas configurações da extensão no Claude Desktop).

Até lá, as outras ferramentas respondem "Sem chave de API ainda: chame pedra_request_access com o e-mail do usuário". A confirmação na caixa de entrada é obrigatória, domínios de e-mail descartáveis são recusados e as solicitações têm limite de taxa. Contas novas começam com os créditos de teste gratuitos da Pedra.

(No ChatGPT e no claude.ai, use o conector hospedado da Pedra: conectá-lo inicia um login onde novos usuários podem criar uma conta.)

Ferramentas

As nove ferramentas de edição de imagem (de melhoria a desfoque) também aceitam propertyId, para salvar o resultado na galeria daquela propriedade, e name, para salvar a foto original lá com esse nome na mesma chamada. O resultado então inclui source (imageId, name) do original. preserveAspectRatio retorna o resultado no tamanho exato da entrada.

Ferramenta	Endpoint	O que faz
`pedra_enhance`	`/enhance`	Melhora iluminação, cor, nitidez
`pedra_enhance_and_correct_perspective`	`/enhance_and_correct_perspective`	Melhoria + correção de perspectiva
`pedra_empty_room`	`/empty_room`	Remove todos os móveis/objetos
`pedra_furnish`	`/furnish`	Ambienta um ambiente virtualmente
`pedra_renovation`	`/renovation`	Reforma paredes/pisos/acabamentos
`pedra_edit_via_prompt`	`/edit_via_prompt`	Edita a partir de um prompt em linguagem natural
`pedra_sky_blue`	`/sky_blue`	Substitui um céu sem graça por azul claro
`pedra_remove_object`	`/remove_object`	Remove um objeto usando uma máscara
`pedra_blur`	`/blur`	Desfoca rostos, placas de veículos, etc.
`pedra_create_video`	`/create_video`	Gera um vídeo da propriedade a partir de imagens
`pedra_update_video`	`/update_video`	Edita um vídeo sem re-renderizar clipes inalterados
`pedra_generate_voice_script`	`/generate_voice_script`	Escreve um roteiro de narração a partir de fotos da propriedade
`pedra_generate_voice`	`/generate_voice`	Transforma um roteiro em uma faixa de áudio de narração
`pedra_music_library`	`/music_library`	Lista faixas de música de fundo, idiomas de voz e vozes de narração
`pedra_list_properties`	`/list_properties`	Lista as propriedades da conta
`pedra_list_property_images`	`/list_property_images`	Lista as fotos de uma propriedade (ou, com `type: "360"`, suas fotos 360°) como URLs
`pedra_create_property`	`/create_property`	Cria uma propriedade
`pedra_add_images_to_property`	`/add_images_to_property`	Adiciona fotos (ou, com `type: "360"`, fotos 360°) a uma propriedade por URL, opcionalmente com `names`
`pedra_add_local_panoramas`	`/add_images_to_property` (em lote)	Somente local: envia arquivos de fotos 360° deste computador para uma propriedade
`pedra_create_upload_link`	`/create_upload_link`	Página sem login para enviar fotos ou fotos 360° de um celular ou computador (`type: "360"` apenas para tours)
`pedra_create_virtual_tour`	`/create_virtual_tour`	Constrói um tour virtual 360° hospedado (a IA nomeia e conecta os ambientes)
`pedra_get_virtual_tour`	`/get_virtual_tour`	Status do tour, link de compartilhamento, código de incorporação, cenas, links
`pedra_list_virtual_tours`	`/list_virtual_tours`	Lista os tours virtuais da conta
`pedra_update_virtual_tour`	`/update_virtual_tour`	Renomeia, reordena, remove ambientes, reconecta, reestiliza (grátis)
`pedra_add_virtual_tour_scenes`	`/add_virtual_tour_scenes`	Adiciona ambientes ao final de um tour
`pedra_credits`	`/credits`	Lê o plano e os créditos restantes
`pedra_feedback`	`/feedback`	Polegar para cima/baixo + opção de devolução de crédito
`pedra_request_access`	`/agent_signup`	Somente sem chave de API: envia por e-mail ao usuário um link para criar/permitir a conta
`pedra_check_access`	`/agent_signup_status`	Somente sem chave de API: verifica a solicitação; uma vez aprovada, todas as ferramentas funcionam na sessão

A maioria das ferramentas de imagem aceita um imageUrl além de alguns parâmetros opcionais; veja o esquema de entrada de cada ferramenta no seu cliente MCP. O imageUrl (e maskUrl, e cada quadro de create_video) aceita qualquer um de:

um URL público de https://,
um URI de data:, ou
um caminho absoluto para um arquivo de imagem local — o servidor o lê do disco e o incorpora como base64 para você, então você pode apontar uma ferramenta para um arquivo que acabou de arrastar sem hospedá-lo antes (.jpg, .jpeg, .png, .webp, .gif, .bmp, .tif/.tiff, .heic/.heif, .avif; até 40 MB).

Observação: uma imagem colada no chat não é um caminho de arquivo, então não pode ser encaminhada para a ferramenta — arraste um arquivo, ou salve a imagem colada e passe o caminho dela. Fotos no celular do usuário passam por pedra_create_upload_link: elas são enviadas em uma página sem login (até 100 arquivos, 24 h), então pedra_list_property_images retorna seus URLs para edição, pedra_create_video ou pedra_create_virtual_tour.

Os envios são limitados por dia: 30 imagens no plano gratuito, 500 nos planos pagos (reinicia à meia-noite UTC), contando toda imagem armazenada fora do aplicativo (pedra_add_images_to_property, pedra_add_local_panoramas, cenas de URL em tours, arquivos de link de envio); acima disso a chamada falha com HTTP 429, upload_limit e nada é armazenado. Links de envio: 5 por dia no gratuito, 50 no pago (upload_link_limit).

Exemplos de prompts após conectar:

"Use a Pedra para ambientar virtualmente https://example.com/empty-living-room.jpg como uma sala de estar minimalista."

"Faça a ambientação virtual de /Users/me/Desktop/empty-living-room.jpg como uma sala de estar minimalista."

"Quantos créditos da Pedra ainda tenho?"

Tours virtuais

Envie suas fotos 360°, receba um tour virtual hospedado, conectado e compartilhável: a IA nomeia os ambientes e posiciona os pontos de navegação de porta a porta. As ferramentas de tour têm os mesmos nomes, descrições e esquemas de entrada do servidor MCP hospedado da Pedra (https://app.pedra.ai/mcp), então um agente se comporta da mesma forma em qualquer um deles.

Um fluxo típico:

Coloque as fotos 360° em uma propriedade.
- Arquivos neste computador → pedra_add_local_panoramas com os caminhos em ordem de caminhada. Esta ferramenta existe apenas neste servidor local: ela lê os arquivos do disco e os envia codificados em base64, 10 por chamada, dentro do limite de 50 MB de solicitação da API. Arquivos acima de ~33 MB não podem ser enviados por aqui.
- Fotos no celular de alguém (ou arquivos grandes) → pedra_create_upload_link com type: "360", e entregue o uploadUrl (sem login, válido por 24 h).
- Fotos já online → pule esta etapa e passe os URLs como scenes.
Construa: pedra_create_virtual_tour com o propertyId (usa todas as fotos 360° na ordem de envio) ou com scenes. Ele retorna um tourId imediatamente.
Aguarde: consulte pedra_get_virtual_tour até que status seja "ready" (cerca de 10 s por ambiente) — então compartilhe tourUrl ou incorpore embedCode. Uma construção com "failed" diz o motivo e não custa nada.
Ajuste com pedra_update_virtual_tour (grátis, instantâneo) ou adicione ambientes com pedra_add_virtual_tour_scenes.

A conexão custa max(3, ceil(rooms/3)) créditos para "sequential" (padrão; cada ambiente ao próximo), 5–160 para "smart" (a IA descobre quais ambientes se conectam) e nada para "none". Excluir um tour é somente via API (não exposto como ferramenta).

"Crie um tour virtual da Pedra da Calle Mayor 12 a partir de /Users/me/360/entrance.jpg, /Users/me/360/living.jpg e /Users/me/360/kitchen.jpg, nessa ordem, e me dê o link."

Como funciona

Este servidor é um wrapper fino sobre @pedra-ai/sdk, que codifica os detalhes do contrato da API:

Síncrono por design (exceto tours virtuais). Cada endpoint de foto e vídeo bloqueia e retorna o(s) URL(s) final(is) no corpo da resposta. Até pedra_create_video consulta no lado do servidor e retorna o videoUrl finalizado inline (pode levar até ~10 minutos; a API mantém a conexão ativa com um heartbeat).
Erros são erros de ferramenta. As respostas 4xx da API (créditos insuficientes, imagem inválida, …) voltam como erros de ferramenta MCP com uma mensagem legível, não como falhas.

Política de Privacidade

Este servidor envia os URLs de imagem/vídeo e os parâmetros que você passa para a API Pedra para realizar a edição solicitada, autenticado com seu PEDRA_API_KEY. Sem chave, pedra_request_access envia o endereço de e-mail que você fornece para a Pedra para que ela possa enviar um link de confirmação; uma chave obtida dessa forma é mantida em memória apenas durante a sessão. Ele não armazena dados por conta própria. Coleta de dados, uso, armazenamento, retenção, compartilhamento com terceiros e informações de contato são cobertos pela política de privacidade da Pedra: https://pedra.ai/privacy.