PicoBerry
An AI 3D workspace for games, VR, and beyond. Generate, remesh, texture, and animate 3D assets.
Open source Open in the app JSON README (API)
About
An AI 3D workspace for games, VR, and beyond. Generate, remesh, texture, and animate 3D assets.
Details
- Kind
- MCP servers
- Topic
- Media, design & games
- Publisher
- umodeler
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.5
- Stars
- 1
- Last push
- 2026-08-12T14:08:02Z
- Repository state
- ativo
- Language
- JavaScript
- License
- MIT
- Added
- 2026-08-29 03:02:18
- Updated
- 2026-08-29 03:02:18
- Origin id
io.github.UModeler/picoberry-mcp
README
<p align="center">
<img src=".github/logo.png" alt="PicoBerry" width="96" height="96">
</p>
<h1 align="center">PicoBerry MCP Server</h1>
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](https://picoberry.ai) `/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](https://api.picoberry.ai/docs/mcp) · [PicoBerry API](https://api.picoberry.ai/docs)
> **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](#get-an-api-key).)
## Install
No install needed — run it with `npx`:
```jsonc
// 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](https://picoberry.ai/dashboard/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 |
## 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 (engine-specific), with optional substring filter. |
| `get_credits` | Current credit balance + plan. |
| `generate_image` | Text → image (+ optional reference image URLs). |
| `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 + animate an existing 3D character → new asset. |
| `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`](https://github.com/ahujasid/blender-mcp) and the
agent can generate with PicoBerry, then import into Blender in one flow:
```jsonc
{
"mcpServers": {
"picoberry": { "command": "npx", "args": ["-y", "@picoberry/mcp-server"], "env": { "PICOBERRY_API_KEY": "pb_live_..." } },
"blender": { "command": "uvx", "args": ["blender-mcp"] }
}
}
```
## Develop
```bash
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](https://glama.ai/mcp/servers/UModeler/picoberry-mcp)
— unclaimed servers get limited discoverability, and `awesome-mcp-servers` gates
its PRs on a Glama badge in CI.
## License
MIT