PicoBerry

PicoBerry MCP Server

Genera modelos 3D, imágenes y animaciones para flujos de trabajo de juegos y 3D desde cualquier cliente MCP — Claude Code, Cursor, Claude Desktop, Cline — sin necesidad de pegamento HTTP. Un envoltorio ligero sobre la API de PicoBerry /v1, para que obtengas el pipeline multi-motor de PicoBerry directamente dentro de tu agente. Varios motores de 3D e imágenes se encuentran detrás de una sola API; llama a list_models para obtener el conjunto en vivo y el costo de cada motor. Los activos generados son borradores — útiles para prototipado e iteración, y pueden ser revisados o refinados para tu proyecto.

📖 Referencia completa: Documentación de API + MCP · API de PicoBerry

No hay una suscripción separada para el MCP o la API. La generación gasta los mismos créditos prepagados de PicoBerry que la aplicación web, por motor, a tarifas que puedes consultar con list_models antes de gastar nada. (Usar la API requiere una compra completada — consulta Obtener una clave de API.)

Instalación

No se necesita instalación — ejecútalo con 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"
      }
    }
  }
}

Cursor usa la misma forma en ~/.cursor/mcp.json.

Obtener una clave de API

Inicia sesión en https://picoberry.ai, abre la pestaña API Keys en tu panel de control y haz clic en Create key. La clave se muestra una sola vez — cópiala inmediatamente y trátala como una contraseña.

El acceso a la API requiere una compra completada: una suscripción o un paquete de créditos de una sola vez. Una compra te habilita permanentemente — no necesitas una suscripción actual. (Una suscripción de pago activa también funciona, por supuesto.)

Variables de entorno

Var	Requerida	Predeterminado	Notas
PICOBERRY_API_KEY	✅	—	pb_live_...
PICOBERRY_API_BASE	—	https://api.picoberry.ai	déjala sin configurar a menos que te hayan dado un host diferente

Herramientas

Herramienta	Qué hace
list_models	Motores + costo de créditos para una categoría (3d / image / parts-board / remesh / texture / animate). Llama antes de generar — no codifiques motores.
list_animation_presets	IDs de presets de animación (específicos del motor), con filtro opcional de subcadena.
get_credits	Saldo de créditos actual + plan.
generate_image	Texto → imagen (+ URLs de imágenes de referencia opcionales).
generate_3d_from_text	Texto → modelo 3D (GLB).
generate_3d_from_image	Imagen → modelo 3D. Individual: image_url o image_path local. Multi-vista (2–4 vistas, mayor fidelidad): image_urls o image_paths, ordenadas [frente, izquierda, atrás, derecha] — solo tripo*/meshy6/hunyuan-3.x.
parts_board	Descompone una imagen en una imagen de tablero de partes explotado (motor fijo del servidor). Entrada asset_id, image_url, o image_path local; alimenta el resultado a generate_3d_from_image para una malla con partes separadas.
remesh	Retopologiza un activo 3D existente → nuevo activo.
texture	Re-texturiza (PBR) un activo 3D existente → nuevo activo.
animate	Auto-rigging + animación de un personaje 3D existente → nuevo activo.
get_asset	Estado + URLs de resultados para un activo.
wait_for_asset	Sondea hasta que un activo termine (o expire el tiempo), luego lo devuelve.
list_my_assets	Navega por tus activos generados.
download_asset	Exporta un activo 3D completado (glb / fbx / obj) → URL firmada.

Cómo funciona la generación

La generación es asíncrona:

1. generate_3d_from_text({ prompt }) → devuelve un { id } de activo.
2. wait_for_asset({ asset_id: id }) → sondea hasta que taskStatus === 2 (exitoso).
3. Lee la URL del resultado de files.model (GLB) o files.image (PNG).

taskStatus: 0 pendiente · 1 procesando · 2 exitoso · 3 fallido. Las URLs de resultados están firmadas y tienen vida corta — descárgalas de inmediato. Los errores vienen con un mensaje accionable (por ejemplo, un motor desconocido devuelve la lista de nombres válidos).

Ejemplo (en un agente)

"Haz un cofre del tesoro low-poly, retopolízalo a 3k tris, y dame un FBX de Unity."

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

Úsalo junto con Blender MCP

Ejecuta esto junto a blender-mcp y el agente puede generar con PicoBerry, luego importar a Blender en un solo flujo:

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

Desarrollo

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

Publicación

Ejecuta Actions → Publish → Run workflow (o empuja una etiqueta v*). Publica en npm y luego en el registro oficial de MCP, en ese orden — el registro valida obteniendo los metadatos npm del paquete y comparando su mcpName contra el name de server.json, así que npm tiene que llegar primero. Un paso de guardia verifica cada invariante (acuerdo de nombre/versión, mayúsculas del namespace, versión no ya en npm) antes de publicar cualquier cosa, porque las versiones de npm son inmutables y una publicación a medias fallida quema el número.

Incrementa version en ambos package.json y server.json (version y packages[0].version) — la guardia falla la ejecución si no coinciden.

Configuración única — sin secretos. Ambas publicaciones se autentican a través del token OIDC de GitHub Actions del workflow (id-token: write). No hay nada que almacenar o rotar.

El único paso es decirle a npm que confíe en este workflow. En npmjs.com ve a @picoberry/mcp-server → Settings → Trusted publishing → GitHub Actions e ingresa:

Campo	Valor
Organización o usuario	UModeler
Repositorio	picoberry-mcp
Nombre del archivo del workflow	publish.yml
Nombre del entorno	(déjalo vacío)
Acciones permitidas	npm publish

El nombre del archivo del workflow debe coincidir exactamente — es parte de lo que npm verifica.

El registro de MCP no necesita configuración en absoluto: mcp-publisher intercambia el token OIDC de Actions, y el registro otorga io.github.<repository_owner>/* del reclamo repository_owner del token. Eso cubre io.github.UModeler/picoberry-mcp y evita el inicio de sesión interactivo del navegador (que además requiere ser propietario de la organización).

Trusted Publishing necesita npm >= 11.5.1, así que el workflow se ejecuta en Node 24 (npm 11.x). Node 22 aún incluye npm 10.9 y fallaría — el pin de node-version es esencial. Un paso de guardia falla la ejecución temprano si el runner alguna vez trae un npm más antiguo.

El namespace se compara byte por byte — io.github.UModeler/..., coincidiendo con el login de la organización de GitHub. Un io.github.umodeler/... en minúsculas es rechazado con 403.

Después de publicar, reclama el listado de Glama — los servidores no reclamados tienen visibilidad limitada, y awesome-mcp-servers condiciona sus PRs a una insignia de Glama en CI.

Licencia

MIT