Skip to main content
Glama
Sign In
PicoBerry MCP Server

PicoBerry MCP Server

by UModeler
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Generate 3D models, images, and animations for game and 3D workflows from any MCP client — Claude Code, Cursor, Claude Desktop, Cline — with no HTTP glue. A thin wrapper over the PicoBerry /v1 API, so you get PicoBerry's multi-engine pipeline directly inside your agent. Several 3D and image engines sit behind one API; call list_models for the live set and each engine's cost. Generated assets are drafts — useful for prototyping and iteration, and can be reviewed or refined for your project.

📖 Full reference: API + MCP docs · PicoBerry API

There's no separate subscription for the MCP or the API. Generation spends the same prepaid PicoBerry credits as the web app, per engine, at rates you can read with list_models before you spend anything. (Using the API does require a completed purchase — see Get an API key.)

Install

No install needed — run it with 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 uses the same shape in ~/.cursor/mcp.json.

Get an API key

Sign in at https://picoberry.ai, open the API Keys tab in your dashboard, and hit Create key. The key is shown once — copy it immediately and treat it like a password.

API access needs a completed purchase: a subscription or a one-off credit pack. A purchase entitles you permanently — you don't need a current subscription. (An active paid subscription works too, of course.)

Environment variables

Var

Required

Default

Notes

PICOBERRY_API_KEY

✅

—

pb_live_...

PICOBERRY_API_BASE

—

https://api.picoberry.ai

leave unset unless you were given a different host

Related MCP server: Context3D MCP Server

Tools

Tool

What it does

list_models

Engines + credit cost for a category (3d / image / parts-board / remesh / texture / animate). Call before generating — don't hardcode engines.

list_animation_presets

Animation preset ids, per engine family (tripo / meshy / pb), with optional substring filter. pb is PB Animation's motion list; each item carries body.

get_credits

Current credit balance.

generate_image

Text → image (+ optional reference image URLs). count (1–4) makes several images in one call → assets[], wait on each id.

generate_3d_from_text

Text → 3D model (GLB).

generate_3d_from_image

Image → 3D model. Single: image_url or local image_path. Multi-view (2–4 views, higher fidelity): image_urls or image_paths, ordered [front, left, back, right] — tripo*/meshy6/hunyuan-3.x only.

parts_board

Decompose one image into an exploded parts-board image (server-fixed engine). Input asset_id, image_url, or local image_path; feed the result to generate_3d_from_image for a parts-separated mesh.

remesh

Retopologize an existing 3D asset → new asset.

texture

Re-texture (PBR) an existing 3D asset → new asset.

animate

Auto-rig (+ optionally animate) an existing 3D asset → new asset. Tripo/Meshy rig humanoids; PB Animation (pb-rig + body: humanoid / quadruped / other) also rigs four-legged and other characters — quadrupeds are rig-only for now.

get_asset

Status + result URLs for one asset.

wait_for_asset

Poll until an asset finishes (or times out), then return it.

list_my_assets

Browse your generated assets.

download_asset

Export a completed 3D asset (glb / fbx / obj) → signed URL.

How generation works

Generation is asynchronous:

  1. generate_3d_from_text({ prompt }) → returns an asset { id }.

  2. wait_for_asset({ asset_id: id }) → polls until taskStatus === 2 (succeeded).

  3. Read the result URL from files.model (GLB) or files.image (PNG).

taskStatus: 0 pending · 1 processing · 2 succeeded · 3 failed. Result URLs are signed and short-lived — download promptly. Errors come back with an actionable message (e.g. an unknown engine returns the list of valid names).

Example (in an agent)

"Make a low-poly treasure chest, retopo it to 3k tris, and give me a 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 it alongside Blender MCP

Run this next to blender-mcp and the agent can generate with PicoBerry, then import into Blender in one flow:

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

Develop

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

Release

Run Actions → Publish → Run workflow (or push a v* tag). It publishes to npm and then to the official MCP registry, in that order — the registry validates by fetching the package's npm metadata and matching its mcpName against server.json's name, so npm has to land first. A guard step checks every invariant (name/version agreement, namespace casing, version not already on npm) before anything is published, because npm versions are immutable and a failed half-publish burns the number.

Bump version in both package.json and server.json (version and packages[0].version) — the guard fails the run if they disagree.

One-time setup — no secrets. Both publishes authenticate over the workflow's GitHub OIDC token (id-token: write). There is nothing to store or rotate.

The only step is telling npm to trust this workflow. On npmjs.com go to @picoberry/mcp-server → Settings → Trusted publishing → GitHub Actions and enter:

Field

Value

Organization or user

UModeler

Repository

picoberry-mcp

Workflow filename

publish.yml

Environment name

(leave empty)

Allowed actions

npm publish

The workflow filename must match exactly — it is part of what npm verifies.

The MCP registry needs no setup at all: mcp-publisher exchanges the Actions OIDC token, and the registry grants io.github.<repository_owner>/* from the token's repository_owner claim. That covers io.github.UModeler/picoberry-mcp and avoids the interactive browser login (which additionally requires org Owner).

Trusted Publishing needs npm >= 11.5.1, so the workflow runs on Node 24 (npm 11.x). Node 22 still bundles npm 10.9 and would fail — the node-version pin is load-bearing. A guard step fails the run early if the runner ever ships an older npm.

The namespace is compared byte-exactly — io.github.UModeler/..., matching the GitHub org's login. A lowercased io.github.umodeler/... is rejected 403.

After publishing, claim the Glama listing — unclaimed servers get limited discoverability, and awesome-mcp-servers gates its PRs on a Glama badge in CI.

License

MIT

Available Tools

14 tools
animateA

Auto-rig an existing 3D character asset and apply an animation, producing a NEW asset (async). Pick preset from list_animation_presets for the SAME engine. Costs credits — see list_models(category='animate'). wait_for_asset → files.model.

Inputs: asset_id (required), engine, preset.

download_assetA

Export a completed 3D asset and get a short-lived signed download URL. glb = a single self-contained file. fbx/obj download as a .zip bundle (model + textures; + Unity .meta files when texture_preset='unity') — unzip before importing. For Unity use fbx (there is no built-in glb importer).

Inputs: asset_id (required), name, format, texture_preset.

generate_3d_from_imageA

Generate a 3D model (GLB) from one image, or from 2–4 views of the same subject (multi-view → higher-fidelity geometry), async. Single: image_url (any public http/https image, or a prior generation's files.image) OR image_path (a local file, uploaded directly — no hosting needed). Multi-view: image_urls OR image_paths, ordered [front, left, back, right] (2–4 views). Not every engine takes multi-view — check supportsMultiView from list_models(category='image-to-3d'); unsupported engines return 400. Local files win over URLs. Then wait_for_asset and read files.model. Costs credits — see list_models(category='image-to-3d') (NOT category='3d', which is the text-to-3D catalog and omits image-only engines).

Inputs: engine, texture, image_url, polycount, +4 more.

generate_3d_from_textA

Generate a game-ready 3D model (GLB) from a text prompt (async). Returns an asset { id }; call wait_for_asset (or poll get_asset) until taskStatus=2 and read files.model (GLB URL). Costs credits — see list_models(category='3d'). Omit engine for the default.

Inputs: prompt (required), engine, texture, polycount.

generate_imageA

Generate a 2D image from a text prompt (async). Returns an asset { id }; then call wait_for_asset (or poll get_asset) until taskStatus=2 and read files.image (PNG URL). Costs credits — see list_models(category='image'). Omit model for the default. Up to 4 reference image URLs can guide the result (best with nano-banana). Set count (1–4) for several images from one call: the top-level fields stay the first image and assets[] lists every image (same batchId) — wait_for_asset on each id. Each image is billed separately; if the balance can't cover all of them nothing is charged. A count above the plan's image slots fails with 400 (don't retry); a busy queue fails with 429 (retry later).

Inputs: prompt (required), count, model, aspect_ratio, +1 more.

get_assetA

Get a generation's status + result. taskStatus: 0=pending 1=processing 2=succeeded 3=failed. When succeeded, files.{model,image,thumbnail,textures} hold signed result URLs (short TTL — download promptly). On failure, read errorDetail.

Inputs: asset_id (required).

get_creditsA

Get the current PicoBerry credit balance for the authenticated key.

Inputs: no named parameters.

list_animation_presetsA

List animation preset ids for the animate tool. Presets are engine-specific (Tripo ~97 / Meshy ~675) — pick one from the SAME engine you animate with. Optionally filter with a case-insensitive substring.

Inputs: engine, search.

list_modelsA

List available generation engines/models and their credit cost for a category. Call this before generating instead of hardcoding engine names. Returns [{ name, label, cost, paidOnly, supportsMultiView, supportsUltraMode, ultraCost, ... }] — use name as the engine/model value. NOTE: the two 3D surfaces are SEPARATE catalogs — 3d is text-to-3D, image-to-3d is image-to-3D. An unrecognized category silently falls back to 3d, so a guessed value returns a plausible list that is missing image-only engines.

Inputs: category.

list_my_assetsA

List your generated assets (newest first, owner-scoped) for browsing/sync. Filter by category (3d/image/…) or keyword.

Inputs: page, limit, keyword, category.

parts_boardA

Decompose one reference image into an exploded "parts board" image (async) — the subject laid out as separated components on one canvas. Input: asset_id (an existing IMAGE asset you own), image_url (a public http/https image), OR image_path (a local file, uploaded directly). Engine/resolution/prompt are server-fixed — no params. Returns an asset { id }; call wait_for_asset (or poll get_asset) until taskStatus=2 and read files.image (the board PNG). Feed that image to generate_3d_from_image for a parts-separated mesh. Costs 80 credits — see list_models(category='parts-board'). Precedence when several are set: image_path > asset_id > image_url.

Inputs: asset_id, image_url, image_path.

remeshA

Retopologize an existing 3D asset into a NEW asset (async). Costs credits — see list_models(category='remesh') (pb-remesh is cheapest). wait_for_asset → files.model.

Inputs: asset_id (required), engine, polycount.

textureA

Re-texture an existing 3D asset (PBR) into a NEW asset (async). Describe the desired look in prompt. Costs credits — see list_models(category='texture'). wait_for_asset → files.model.

Inputs: asset_id (required), engine, prompt.

wait_for_assetA

Poll an asset until it finishes (taskStatus 2 or 3) or the timeout elapses, then return the final asset. Use right after generate_* / remesh / texture / animate. 3D generations can take several minutes.

Inputs: asset_id (required), timeout_seconds, poll_interval_seconds.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4.1/5.0

    Scored across 14 tools

    Disambiguation4/5

    Each generation tool targets a distinct input modality (text→image, text→3D, image→3D) and the post-processing tools (remesh, texture, animate, parts_board) each transform an existing asset in a clearly different way. The only real overlaps are get_asset vs wait_for_asset (polling wrapper) and get_asset vs download_asset (result URLs vs export/conversion), but the descriptions explicitly clarify the difference.

    Naming Consistency3/5

    Most tools follow a clean verb_noun pattern (get_credits, generate_image, list_models, wait_for_asset), but the set mixes in bare verbs (remesh, texture, animate) and a bare noun (parts_board), where `texture` also ambiguously reads as a noun. It remains readable and semantically apt, but the convention is not uniform.

    Tool Count5/5

    Fourteen tools map cleanly onto the platform's lifecycles: generation (3), post-processing (4), asset retrieval/inspection (3), catalog discovery (3), and billing (1). No tool feels like filler and none of the workflows require an excessive number of calls beyond the inherent async wait.

    Completeness4/5

    The surface covers generation, transformation, polling, export, listing, credit balance, and model/preset discovery — a full end-to-end workflow. Minor gaps exist: no asset deletion or cancellation of an in-flight task, and no way to inspect/top up credits beyond a balance read.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers