PicoBerry

PicoBerry MCP Server

Gere modelos 3D, imagens e animações para jogos e fluxos de trabalho 3D a partir de qualquer cliente MCP — Claude Code, Cursor, Claude Desktop, Cline — sem necessidade de integração HTTP. Um wrapper leve sobre a API PicoBerry /v1, para que você tenha o pipeline multi-motor da PicoBerry diretamente dentro do seu agente. Vários motores 3D e de imagem ficam atrás de uma única API; chame list_models para obter o conjunto atual e o custo de cada motor. Os ativos gerados são rascunhos — úteis para prototipagem e iteração, e podem ser revisados ou refinados para o seu projeto.

📖 Referência completa: Documentação da API + MCP · API PicoBerry

Não há assinatura separada para o MCP ou para a API. A geração consome os mesmos créditos PicoBerry pré-pagos do aplicativo web, por motor, a taxas que você pode consultar com list_models antes de gastar qualquer coisa. (Usar a API exige uma compra concluída — veja Obter uma chave de API.)

Instalação

Nenhuma instalação necessária — execute com npx:

// Claude Code:  .mcp.json   ·   Claude Desktop:  claude_desktop_config.json
{
  "mcpServers": {
    "picoberry": {
      "command": "npx",
      "args": ["-y", "@picoberry/mcp-server"],
      "env": {
        "PICOBERRY_API_KEY": "pb_live_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

O Cursor usa a mesma estrutura em ~/.cursor/mcp.json.

Obter uma chave de API

Entre em https://picoberry.ai, abra a aba API Keys no seu painel e clique em Create key. A chave é exibida apenas uma vez — copie-a imediatamente e trate-a como uma senha.

O acesso à API exige uma compra concluída: uma assinatura ou um pacote de créditos avulso. Uma compra dá direito permanente — você não precisa de uma assinatura atual. (Uma assinatura paga ativa também funciona, é claro.)

Variáveis de ambiente

Variável	Obrigatória	Padrão	Observações
PICOBERRY_API_KEY	✅	—	pb_live_...
PICOBERRY_API_BASE	—	https://api.picoberry.ai	deixe sem definir, a menos que você tenha recebido um host diferente

Ferramentas

Ferramenta	O que faz
list_models	Motores + custo em créditos para uma categoria (3d / image / parts-board / remesh / texture / animate). Chame antes de gerar — não codifique motores.
list_animation_presets	IDs de predefinições de animação (específicos do motor), com filtro opcional de substring.
get_credits	Saldo de créditos atual + plano.
generate_image	Texto → imagem (+ URLs de imagem de referência opcionais).
generate_3d_from_text	Texto → modelo 3D (GLB).
generate_3d_from_image	Imagem → modelo 3D. Única: image_url ou image_path local. Multi-visão (2–4 visões, maior fidelidade): image_urls ou image_paths, ordenadas [frente, esquerda, trás, direita] — apenas tripo*/meshy6/hunyuan-3.x.
parts_board	Decompor uma imagem em uma imagem de quadro de peças explodido (motor fixo do servidor). Entrada asset_id, image_url ou image_path local; alimente o resultado em generate_3d_from_image para uma malha com peças separadas.
remesh	Retopologizar um ativo 3D existente → novo ativo.
texture	Re-texturizar (PBR) um ativo 3D existente → novo ativo.
animate	Auto-rig + animar um personagem 3D existente → novo ativo.
get_asset	Status + URLs de resultado para um ativo.
wait_for_asset	Consultar até que um ativo termine (ou expire), então retorná-lo.
list_my_assets	Navegar pelos seus ativos gerados.
download_asset	Exportar um ativo 3D concluído (glb / fbx / obj) → URL assinada.

Como a geração funciona

A geração é assíncrona:

1. generate_3d_from_text({ prompt }) → retorna um { id } de ativo.
2. wait_for_asset({ asset_id: id }) → consulta até taskStatus === 2 (sucesso).
3. Leia a URL do resultado de files.model (GLB) ou files.image (PNG).

taskStatus: 0 pendente · 1 processando · 2 sucesso · 3 falha. As URLs de resultado são assinadas e de curta duração — baixe imediatamente. Erros retornam com uma mensagem acionável (por exemplo, um motor desconhecido retorna a lista de nomes válidos).

Exemplo (em um agente)

"Faça um baú de tesouro low-poly, retopologize para 3k tris e me dê um Unity FBX."

list_models(category="3d")                         → pick an engine
generate_3d_from_text(prompt="low-poly treasure chest")  → { id: A }
wait_for_asset(asset_id=A)                          → taskStatus 2
remesh(asset_id=A, polycount=3000)                  → { id: B }
wait_for_asset(asset_id=B)
download_asset(asset_id=B, format="fbx", texture_preset="unity")  → signed URL

Use junto com o Blender MCP

Execute isso ao lado de blender-mcp e o agente pode gerar com a PicoBerry e depois importar para o Blender em um único fluxo:

{
  "mcpServers": {
    "picoberry": { "command": "npx", "args": ["-y", "@picoberry/mcp-server"], "env": { "PICOBERRY_API_KEY": "pb_live_..." } },
    "blender":   { "command": "uvx", "args": ["blender-mcp"] }
  }
}

Desenvolvimento

npm install
npm run build      # tsc → dist/
PICOBERRY_API_KEY=pb_live_... npm start

Lançamento

Execute Actions → Publish → Run workflow (ou envie uma tag v*). Ele publica no npm e depois no registro oficial do MCP, nessa ordem — o registro valida buscando os metadados do pacote no npm e correspondendo seu mcpName ao name de server.json, então o npm precisa ser publicado primeiro. Uma etapa de verificação valida cada invariante (concordância de nome/versão, capitalização do namespace, versão já não no npm) antes de qualquer publicação, porque as versões do npm são imutáveis e uma meia-publicação falha queima o número.

Aumente version em ambos package.json e server.json (version e packages[0].version) — a verificação falha a execução se eles discordarem.

Configuração única — sem segredos. Ambas as publicações autenticam via token OIDC do GitHub Actions do workflow (id-token: write). Não há nada para armazenar ou rotacionar.

O único passo é dizer ao npm para confiar neste workflow. Em npmjs.com, vá para @picoberry/mcp-server → Settings → Trusted publishing → GitHub Actions e insira:

Campo	Valor
Organização ou usuário	UModeler
Repositório	picoberry-mcp
Nome do arquivo do workflow	publish.yml
Nome do ambiente	(deixe vazio)
Ações permitidas	npm publish

O nome do arquivo do workflow deve corresponder exatamente — faz parte do que o npm verifica.

O registro do MCP não precisa de configuração alguma: mcp-publisher troca o token OIDC do Actions, e o registro concede io.github.<repository_owner>/* da declaração repository_owner do token. Isso cobre io.github.UModeler/picoberry-mcp e evita o login interativo no navegador (que adicionalmente exige o proprietário da organização).

Trusted Publishing precisa de npm >= 11.5.1, então o workflow roda em Node 24 (npm 11.x). O Node 22 ainda inclui npm 10.9 e falharia — o pin node-version é essencial. Uma etapa de verificação falha a execução cedo se o runner enviar um npm mais antigo.

O namespace é comparado byte a byte — io.github.UModeler/..., correspondendo ao login da organização no GitHub. Um io.github.umodeler/... em minúsculas é rejeitado com 403.

Após publicar, reivindique a listagem no Glama — servidores não reivindicados têm descoberta limitada, e awesome-mcp-servers condiciona seus PRs a um selo Glama no CI.

Licença

MIT