Photocraft MCP Server – instalação, configuração e ferramentas

O que é o servidor MCP do Photocraft

O servidor MCP do Photocraft é um endpoint Model Context Protocol integrado à pilha de automação do PhotoCraft. Ele fala MCP sobre entrada e saída padrão, então um cliente de IA como Claude Code, Claude Desktop, Cursor ou VS Code consegue descobrir comandos de edição, executá-los um a um ou em lote, inspecionar o documento aberto e gerar prévias — sem que ninguém clique na interface.

O servidor vem dentro do photocraft-cli, o companheiro de linha de comando do editor desktop open source PhotoCraft. Este site hospeda o editor web do PhotoCraft que roda no navegador; o servidor MCP pertence ao release desktop, e a versão para navegador não o expõe. Tudo abaixo segue o release upstream v0.12.0 que este site acompanha, conferido na documentação upstream em outubro de 2026.

O que você precisa

• Uma instalação de um release do PhotoCraft que inclua o photocraft-cli (veja a tabela abaixo).
• Um cliente MCP capaz de registrar um servidor stdio: Claude Code, Claude Desktop, Cursor, VS Code e ferramentas semelhantes servem.
• Uma pasta de trabalho para as imagens. O servidor só lê e grava dentro das raízes que você conceder na inicialização.

Onde fica a CLI

Sistema	Local da CLI
Windows (MSI)	C:\Program Files\PhotoCraft\photocraft-cli.exe por padrão; não é adicionada ao PATH
Linux (deb, rpm)	/usr/bin/photocraft-cli
macOS	um zip separado do photocraft-cli na página de releases; o pacote .app contém apenas o app desktop

Adicionar o servidor ao Claude Code

O Claude Code registra um servidor stdio com um comando. Passe a pasta que o agente pode ler e gravar. No Windows, com a pasta de instalação padrão:

claude mcp add photocraft -- "C:\Program Files\PhotoCraft\photocraft-cli.exe" mcp --automation-read-root "C:\work\project" --automation-write-root "C:\work\project"

No Linux — ou no macOS com a CLI descompactada no PATH — o mesmo registro fica mais curto:

claude mcp add photocraft -- photocraft-cli mcp --automation-read-root /work/project --automation-write-root /work/project

Reinicie o cliente e peça ao agente para listar as ferramentas do Photocraft. Se command_list devolver comandos do motor, o registro funcionou.

Claude Desktop, Cursor e VS Code

Clientes que leem uma configuração JSON usam o mesmo comando e os mesmos argumentos. Para o Cursor (~/.cursor/mcp.json) e o Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "photocraft": {
      "command": "/usr/bin/photocraft-cli",
      "args": [
        "mcp",
        "--automation-read-root",
        "/work/project",
        "--automation-write-root",
        "/work/project"
      ]
    }
  }
}

No Windows, aponte command para o caminho completo do photocraft-cli.exe e mantenha as aspas ao redor do caminho. O VS Code aceita o mesmo bloco mcpServers no seu mcp.json. Salve o arquivo, reinicie o cliente e abra o painel MCP: o servidor photocraft deve aparecer com suas ferramentas listadas.

Modos headless e bridge

O servidor roda em dois backends. O modo headless — a configuração acima — inicia um motor privado dentro do processo da CLI e faz sua própria E/S de arquivos. Nenhuma janela desktop é necessária, o que serve para trabalho em lote roteirizado.

O modo bridge encaminha cada chamada de ferramenta para um aplicativo desktop iniciado com photocraft --control:

photocraft-cli mcp --bridge 127.0.0.1:7878 --control-token-file /private/path/control.token

O modo bridge acrescenta as ferramentas de inspeção de UI listadas abaixo e usa as raízes configuradas no processo desktop. Escolha-o quando quiser observar o mesmo documento na tela enquanto o agente trabalha.

Ferramentas principais

Ferramenta	O que faz	Argumentos principais
command_list	Descobre ids de comandos do motor, documentação de parâmetros e estado de ativação	filter, enabled_only
command_run	Executa um comando do motor	id, params, wait
command_batch	Executa passos ordenados como uma entrada de histórico; não é uma transação atômica	steps, stop_on_error
doc_inspect	Árvore de camadas, histórico e seleção; uma sessão vazia responde document: null	—
render_preview	Prévia PNG limitada do documento atual	index, max_side (padrão 1024, máximo 2048)
ui_inspect, ui_screenshot	Estado ao vivo do app e captura da janela; somente no modo bridge	—

Ferramentas antigas de documento, sessão e job continuam listadas, incluindo a grafia documentada doc_render_preview. Não há aliases legados ocultos, e toda ferramenta traz um título e dicas de anotação.

Dois recursos MCP expõem estado ao vivo como JSON: photocraft://document espelha doc_inspect e photocraft://commands espelha command_list. As leituras de recursos não usam cache, então um agente pode reverificar o estado entre passos em vez de confiar numa cópia velha.

Prompts de exemplo

• Liste os comandos do Photocraft para redimensionamento e exportação, depois converta em lote cada PNG da pasta concedida para 1600 pixels no lado maior.
• Inspecione o documento aberto, descreva a pilha de camadas e gere uma prévia para eu conferir o estado atual.
• Crie um documento e uma linha do tempo, renderize uma sequência PNG com notificações de progresso e cancele o job se passar de um minuto.

Os smart objects também são roteirizáveis. layer.smartObjects.editContents e layer.smartObjects.convertToLayers rodam via command_run; salve conteúdos aninhados de dentro para fora e então faça doc_save do documento pai num caminho concedido.

O Render Video informa progresso de quadros quando a requisição carrega um progress token e para num limite de quadro ao ser cancelado. Nomes de arquivo existentes são recusados, então um job cancelado ou falho não substitui uma exportação anterior.

Modelo de segurança

O transporte stdio não abre nenhum listener de rede; o cliente fala com a CLI pelas próprias pipes. A autorização sobre arquivos é concedida por inicialização: a raiz de leitura e a raiz de gravação são as únicas pastas que o servidor pode tocar, e omitir uma raiz remove essa autoridade por completo. Caminhos precisam resolver dentro das raízes concedidas. O modo bridge autentica a conexão de loopback com um bearer token antes de qualquer chamada de controle.

Dois limites importam. O servidor atual não emite sessões com escopo e não separa ferramentas confiáveis de ferramentas de alto impacto: a autenticação prova a posse do token, não um acesso somente ao documento. Não exponha nenhum dos transportes por meio de broker não confiável, wrapper de shell, proxy ou serviço remoto sem adicionar uma barreira de política externa. As capacidades de filesystem estão implementadas; as capacidades gerais de ferramenta permanecem uma proposta de design upstream.

Solução de problemas

• photocraft-cli não encontrado no Windows — a instalação MSI não edita o PATH. Use o caminho completo entre aspas no comando de registro.
• Nenhuma CLI no macOS após instalar — o .app contém só o editor desktop. Baixe o zip macOS separado do photocraft-cli nos assets do release.
• -32602 numa chamada de ferramenta — nome de argumento desconhecido. O erro aponta a chave problemática antes de qualquer execução. Confira a grafia contra a saída de command_list.
• Resultado de ferramenta com isError: true — o comando em si falhou. Leia a mensagem; a sessão continua atendendo.
• document: null do doc_inspect — nenhum documento aberto. Crie ou abra um antes.
• A prévia parece desatualizada — as prévias renderizam o documento atual. Confirme que o agente editou o documento que inspecionou e releia o recurso ao vivo; leituras não usam cache.

Perguntas frequentes

Posso conectar o MCP ao editor web deste site? Não. A versão de navegador roda localmente na sua aba e não tem endpoint MCP. O servidor vem com o release desktop. Você pode experimentar o editor no navegador e rodar a CLI ao lado, nos arquivos que exportar.

Preciso deixar o app desktop aberto? Só para o modo bridge e as ferramentas de UI. O modo headless roda inteiramente dentro da CLI.

Qual versão este guia descreve? A upstream v0.12.0, o release que este site fixa e hospeda. Releases mais novos podem adicionar ou mudar ferramentas; a documentação MCP upstream vinculada é autoritativa.

Quanto custa? O PhotoCraft é open source sob MIT e Apache-2.0, e o servidor MCP faz parte do mesmo pacote. Veja a página de código-fonte e licenças.

Guias relacionadas: downloads de releases, visão geral de recursos com limites do navegador e tutoriais.