O Claude Code escreve suas páginas, mas não consegue desenhar as imagens delas. Este artigo mostra como registrar um servidor MCP de geração de imagens, escolher o escopo certo, comparar os servidores mais usados e conectar o PicassoIA para imagens e vídeos, com soluções para erros comuns.
O Claude Code consegue montar uma landing page em minutos, mas não consegue desenhar a imagem principal dela. Se você pedir um banner, um mockup de produto ou um conjunto de miniaturas para o blog, vai receber código SVG, um caminho provisório ou um educado "não consigo gerar imagens". Um servidor MCP de geração de imagens fecha essa lacuna. Depois de registrado, o Claude Code chama um modelo de imagem como uma ferramenta, salva o arquivo dentro do seu repositório e o conecta ao HTML ou ao markdown que ele já está editando, tudo em uma única sessão.
Este artigo mostra como as peças se conectam, os comandos exatos para registrar um servidor, uma comparação lado a lado das opções que as pessoas realmente usam e como ligar o conector do PicassoIA para imagens e vídeos. Os comandos seguem a documentação atual do Claude Code. O que eu não consegui confirmar, como a URL de um servidor privado, aparece como um marcador de posição em vez de um palpite.
O Claude Code trabalha no seu terminal, lê seus arquivos, executa comandos e edita código. Esse fluxo é rápido até a primeira <img>. Aí você sai da sessão, abre um gerador separado, baixa um arquivo, renomeia, coloca na pasta certa e cola o caminho de volta. Cada etapa quebra o fluxo, e o prompt que você escreveu nunca chega à página para a qual foi feito.
O MCP, o Model Context Protocol, é um padrão aberto que permite a um cliente de IA chamar ferramentas externas. Um servidor de imagens expõe uma ou mais ferramentas, normalmente algo como generate_image, e o Claude Code as lista sob um nome previsível: mcp__<server-name>__<tool-name>. Um servidor chamado image-gen com uma ferramenta generate_image aparece como mcp__image-gen__generate_image.
Com isso no lugar, um único pedido faz o trabalho inteiro:
💡 Dica: Mantenha o nome do servidor curto e em minúsculas. Ele aparece em toda chamada de ferramenta e em todo pedido de permissão, e
image-gené mais legível do que um nome de produto longo.
Três partes estão envolvidas, e confundi-las causa a maior parte da confusão na configuração.
| Parte | O que é | Exemplo |
|---|---|---|
| Cliente | O aplicativo que chama as ferramentas | Claude Code |
| Servidor | Um processo ou endpoint hospedado que fala MCP | mcp-image, um conector do PicassoIA |
| Provedor | A plataforma que executa o modelo de imagem | OpenAI, Google, Replicate, PicassoIA |
O servidor é o tradutor. Ele aceita uma chamada de ferramenta do Claude Code, transforma em um pedido que o provedor aceita e devolve o resultado. O Claude Code oferece quatro transportes: stdio, http, sse e ws. Na prática, você escolhe entre dois. stdio inicia um processo local na sua máquina, normalmente por meio de npx. http aponta para uma URL remota que outra pessoa mantém no ar.
Os servidores tratam a saída de duas formas, e a diferença importa. Alguns salvam o arquivo no disco e devolvem o caminho. mcp-image grava em uma pasta que você define, e create-image-mcp devolve metadados do arquivo em vez de dados em base64. Outros devolvem uma URL ou dados de imagem embutidos.
A documentação do Claude Code informa que as imagens nos resultados de ferramentas contam para o limite de MAX_MCP_OUTPUT_TOKENS. Um aviso aparece com 10.000 tokens, e o teto padrão é de 25.000. Um servidor que devolve um caminho curto ou uma URL fica bem abaixo dessa linha. Um que devolve imagens grandes embutidas pode atingi-la rapidamente.
claude --version.claude mcp add.claude mcp list.Para um servidor local stdio, o formato é este:
claude mcp add --transport stdio --env <PROVIDER_VARIABLE>=<your-credential> --env IMAGE_OUTPUT_DIR=/absolute/path/to/public/images image-gen -- npx -y mcp-image
Tudo antes de -- pertence ao Claude Code. Tudo depois vai para o servidor sem alterações. Se você esquecer o --, a CLI tenta ler as flags do seu servidor como se fossem dela. O nome exato da variável vem do README do servidor, porque cada provedor usa o seu.
Para um servidor hospedado, troque o transporte para http:
claude mcp add --transport http image-gen <server-url> --header "Authorization: Bearer <your-credential>"
⚠️ Usuários do Windows: No Windows nativo, fora do WSL, servidores iniciados com
npxprecisam de um wrapper:claude mcp add --transport stdio image-gen -- cmd /c npx -y mcp-image. Sem ele, o servidor pode não iniciar.
| Escopo | Armazenado em | Quem vê | Use para |
|---|---|---|---|
local (padrão) | ~/.claude.json, dentro do seu projeto | Só você, em um projeto | Testar um servidor novo |
project | .mcp.json na raiz do repositório | Todos que clonam o repositório | Ferramentas padronizadas da equipe |
user | ~/.claude.json, no nível superior | Só você, em todos os projetos | Ferramentas pessoais |
Acrescente --scope project ou --scope user ao comando. Quando o mesmo nome existe em vários escopos, o local prevalece sobre o de projeto, e o de projeto prevalece sobre o de usuário.
O escopo de projeto combina com trabalho de imagens porque a equipe inteira recebe a mesma configuração. Mas não faça commit de credenciais. .mcp.json aceita expansão de ${VAR} em command, args, env, url e headers, então o arquivo guarda uma referência e cada desenvolvedor fornece o valor pelo próprio shell:
{
"mcpServers": {
"image-gen": {
"type": "stdio",
"command": "npx",
"args": ["-y", "mcp-image"],
"env": {
"IMAGE_OUTPUT_DIR": "${IMAGE_OUTPUT_DIR}",
"<PROVIDER_VARIABLE>": "${<PROVIDER_VARIABLE>}"
}
}
}
}
O Claude Code pede aprovação antes de executar um servidor vindo de um .mcp.json de projeto, então, na primeira sessão de um colega, aparece o status pending approval até que ele aceite.
Execute claude mcp list. Cada servidor recebe um status: Connected, Failed to connect, Needs authentication ou Pending approval. claude mcp get image-gen mostra os detalhes de um servidor específico. Dentro de uma sessão, /mcp abre o mesmo painel, e /mcp reconnect all tenta de novo qualquer item que tenha falhado.
Depois, teste com um pedido pequeno: "Gere uma imagem 16:9 de uma caneca de cerâmica sobre uma mesa de madeira e salve em public/images/test.jpg." Se a chamada da ferramenta aparecer como mcp__image-gen__generate_image e um arquivo surgir na pasta, o servidor funciona.
A tabela abaixo vem da listagem de cada projeto, então confira o README para ver as opções atuais antes de instalar. Eu não fiz benchmark da qualidade de imagem entre eles, porque a qualidade depende muito mais do modelo por trás de um servidor do que do próprio servidor.
| Servidor | Modelos por trás | Instalação | Saída | Melhor para |
|---|---|---|---|---|
mcp-image | Gemini (padrão), OpenAI, BytePlus Seedream | npx -y mcp-image | Salvo em IMAGE_OUTPUT_DIR | Um servidor, três provedores |
create-image-mcp | OpenAI GPT Image | npm install -g @gpriday/create-image-mcp | Salvo no disco, caminho devolvido | Usuários da OpenAI que precisam de máscaras e inpainting |
| Servidores da comunidade Replicate | Modelos hospedados no Replicate | Pacote Python do PyPI | Varia por servidor | Ampla escolha de modelos, trabalhos em lote |
| Servidores da comunidade FLUX | Modelos FLUX | Script Python local | Varia por servidor | Configurações autogerenciadas |
| Conector do PicassoIA | Modelos de imagem e vídeo do PicassoIA | Conector ou URL http | URLs de resultado após consulta | Imagens e vídeos em um só lugar |
mcp-image expõe uma única ferramenta generate_image que cuida de texto para imagem e de edição a partir de uma imagem de entrada. Ele oferece predefinições rápida, equilibrada e de qualidade, e proporções de até 21:9. Você define uma credencial para o provedor que escolher, além de uma pasta de saída absoluta.
create-image-mcp funciona só com a OpenAI. Sua ferramenta create_image aceita tamanhos de até 4K, configurações de qualidade, transparência, várias variações por chamada e máscaras para inpainting. Ele salva no disco e responde com um caminho, o que mantém baixo o custo em tokens.
Servidores da comunidade Replicate, como mcp-server-replicate, expõem texto para imagem, imagem para imagem e edição em tudo o que o Replicate hospeda, e um deles processa até 5 imagens por vez. Escolha essa rota quando quiser trocar de modelo com frequência.
A contrapartida de todo servidor local é a manutenção. Você gerencia versões do Node ou do Python, paga o provedor diretamente e atualiza o pacote por conta própria.
Um servidor hospedado elimina a etapa de instalação. Você adiciona uma URL e uma credencial, e o provedor cuida do resto. O Claude Code tenta de novo uma conexão remota interrompida até cinco vezes, com intervalos crescentes, então quedas breves se resolvem sem sua ajuda. O custo é depender do tempo de atividade e das regras do plano de outra pessoa.
O Claude Code também carrega conectores da sua conta claude.ai quando você entra com ela. Eles têm a menor precedência, abaixo dos servidores locais, de projeto e de usuário, e definir ENABLE_CLAUDEAI_MCP_SERVERS=false os desativa.
O PicassoIA oferece geração de imagens, edição e vídeo em um único conector, o que combina com projetos que precisam de uma imagem estática e de um clipe curto que combine com ela.
O conector do PicassoIA oferece nove ferramentas: generate_image, edit_image, generate_video_picassoia, generate_video_seedance, get_generation, list_generations, list_models, get_account e cancel_generation.
A geração é assíncrona. Uma chamada de geração devolve um predict_id assim que uma GPU aceita o trabalho, e get_generation informa o status até que apareça succeeded ou failed. O Claude Code executa esse ciclo de consulta por você quando você pede o resultado.
A API para desenvolvedores por trás dele segue um design no estilo Replicate. A URL base é https://api.picassoia.com/v1, a autenticação é um segredo Bearer que começa com pia_sk_, e os principais endpoints são POST /v1/models/{owner}/{name}/predictions e GET /v1/predictions/{id}. Planeje com base nestes limites:
💡 Verifique seu plano primeiro. O PicassoIA lista o acesso à API e ao MCP na página de preços, e os detalhes podem variar entre os planos. Confirme que o seu plano inclui isso antes de montar um fluxo de trabalho em cima.
| Modelo | Use para |
|---|---|
| PicassoIA Image | Trabalho cotidiano de texto para imagem |
| PicassoIA Image Editor Pro | Edições e retoques em uma imagem existente |
| PicassoIA Video | Clipes curtos a partir de texto ou de uma imagem estática |
| Seedance 2.5 Lite | Vídeo com áudio, listado para clipes de até 10 segundos |
O catálogo mais amplo do PicassoIA tem muitos outros modelos de imagem, incluindo GPT Image 2, Seedream 5 Lite, Flux 2 Pro e Nano Banana 2. Teste um prompt no aplicativo web primeiro, escolha o visual de que gosta e então peça ao Claude Code para reproduzi-lo.
Para a parte de texto do trabalho, o mesmo catálogo lista Claude Sonnet 5 e Claude Opus 4.7, úteis para rascunhar variações de prompt antes de colá-las em uma sessão.
Uma imagem estática e um clipe curto costumam andar juntos, como uma foto principal e um banner em loop. Peça ao Claude Code para gerar a imagem com o PicassoIA Image e depois passe o resultado para uma ferramenta de vídeo como quadro inicial. Execute um vídeo por vez, porque cada tarefa ocupa uma das suas cinco vagas simultâneas.
http com a URL da página de conexões MCP da sua conta em picassoia.com/en/mcp/accounts. O PicassoIA não publica essa URL nas suas páginas públicas, então copie-a da sua conta.claude mcp list, ou digite /mcp em uma sessão, e confirme que o PicassoIA aparece como conectado.list_models.public/images/hero.jpg."get_generation e, em seguida, busca a URL do resultado para sua pasta e atualiza a marcação.edit_image com o PicassoIA Image Editor Pro para ajustes de tom e detalhe.Os prompts de imagem dentro do Claude Code têm uma vantagem sobre um formulário web: o agente consegue ver o seu arquivo. Aproveite isso. Descreva a função da imagem, não só o conteúdo, e informe o caminho do arquivo e o tamanho para que nada precise de uma segunda rodada.
| Pedido fraco | Pedido forte |
|---|---|
| "Faça uma imagem de cabeçalho bonita" | "Cabeçalho 16:9 para a página de preços, uma xícara de cerâmica sobre uma mesa de nogueira, luz de janela vinda da esquerda, sem texto" |
| "Adicione algumas fotos" | "Gere 3 imagens, uma para cada título de seção em features.html, e salve em public/images/" |
| "Corrija a imagem" | "Edite hero.jpg: tons mais quentes, remova o cabo no canto inferior esquerdo" |
Três hábitos economizam mais tempo:
CLAUDE.md do seu projeto para que toda sessão comece com os mesmos padrões.## Images
- Generate images with the image-gen server, 16:9 unless the layout says otherwise
- Save to public/images/ with lowercase hyphenated names
- Write one-sentence alt text that describes the scene
- Photographic style, natural light, no text inside the image
💡 Dica: Indique a pasta de saída em
CLAUDE.md, não em cada prompt. Essa única linha impede que os arquivos caiam na raiz do repositório.
Execute o comando do servidor manualmente em um terminal normal. Uma instalação ausente do Node, um erro de digitação no nome do pacote ou uma variável de ambiente não definida aparecem logo. Em seguida, confira se -- fica entre as opções do Claude e o comando do servidor. No Windows, adicione o wrapper cmd /c mencionado antes. Se o servidor só demora para iniciar, aumente o limite de inicialização, por exemplo MCP_TIMEOUT=10000 claude, que é medido em milissegundos. Depois execute /mcp reconnect all.
Se um resultado de ferramenta acionar o aviso de 10.000 tokens, o servidor provavelmente está devolvendo dados de imagem embutidos. Troque para um servidor que salva no disco ou devolve uma URL. Aumentar o teto com MAX_MCP_OUTPUT_TOKENS=50000 claude funciona como último recurso, mas gasta contexto que você preferiria reservar para o código.
O Claude Code move chamadas de ferramentas que duram mais de dois minutos para uma tarefa em segundo plano, que você pode acompanhar em /tasks. Com um conector assíncrono, uma tarefa lenta geralmente significa uma fila cheia. Pedir doze imagens de uma vez em uma conta limitada a cinco previsões simultâneas faz sete delas esperarem. Peça cinco por vez e use cancel_generation para uma tarefa que você não precisa mais.
A configuração leva cerca de dez minutos: um comando, uma escolha de escopo, um prompt de teste. Depois disso, cada página que o Claude Code construir pode sair com fotos próprias em vez de espaços reservados.
Comece pequeno. Teste um prompt no PicassoIA Image, refine um resultado com o PicassoIA Image Editor Pro e depois anime o seu favorito com o PicassoIA Video. Quando o visual estiver certo, entregue o mesmo prompt ao Claude Code e deixe que ele execute o ciclo dentro do seu projeto. Veja a lista completa de modelos em picassoia.com/en/all-models e crie suas próprias imagens com o PicassoIA hoje.
Escolha seu idioma
