picoberry-mcp

PicoBerry MCP Server

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 , 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

Tools

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:

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./*` 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