{
  "markdown": "<p align=\"center\">\n  <img src=\".github/logo.png\" alt=\"PicoBerry\" width=\"96\" height=\"96\">\n</p>\n\n<h1 align=\"center\">PicoBerry MCP Server</h1>\n\nGenerate **3D models, images, and animations** for game and 3D workflows from any\nMCP client — Claude Code, Cursor, Claude Desktop, Cline — with no HTTP glue. A thin\nwrapper over the [PicoBerry](https://picoberry.ai) `/v1` API, so you get PicoBerry's\nmulti-engine pipeline directly inside your agent. Several 3D and image engines\nsit behind one API; call `list_models` for the live set and each engine's cost.\nGenerated assets are drafts — useful for prototyping and iteration, and can be\nreviewed or refined for your project.\n\n📖 **Full reference:** [API + MCP docs](https://api.picoberry.ai/docs/mcp) · [PicoBerry API](https://api.picoberry.ai/docs)\n\n> **There's no separate subscription for the MCP or the API.** Generation spends\n> the same prepaid PicoBerry credits as the web app, per engine, at rates you can\n> read with `list_models` before you spend anything. (Using the API does require\n> a completed purchase — see [Get an API key](#get-an-api-key).)\n\n## Install\n\nNo install needed — run it with `npx`:\n\n```jsonc\n// Claude Code:  .mcp.json   ·   Claude Desktop:  claude_desktop_config.json\n{\n  \"mcpServers\": {\n    \"picoberry\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@picoberry/mcp-server\"],\n      \"env\": {\n        \"PICOBERRY_API_KEY\": \"pb_live_xxxxxxxxxxxxxxxx\"\n      }\n    }\n  }\n}\n```\n\nCursor uses the same shape in `~/.cursor/mcp.json`.\n\n### Get an API key\n\nSign in at <https://picoberry.ai>, open the **[API Keys](https://picoberry.ai/dashboard/api-keys)**\ntab in your dashboard, and hit **Create key**. The key is shown once — copy it\nimmediately and treat it like a password.\n\nAPI access needs a completed purchase: a subscription **or a one-off credit\npack**. A purchase entitles you permanently — you don't need a *current*\nsubscription. (An active paid subscription works too, of course.)\n\n### Environment variables\n\n| Var | Required | Default | Notes |\n|-----|----------|---------|-------|\n| `PICOBERRY_API_KEY` | ✅ | — | `pb_live_...` |\n| `PICOBERRY_API_BASE` | — | `https://api.picoberry.ai` | leave unset unless you were given a different host |\n\n## Tools\n\n| Tool | What it does |\n|------|--------------|\n| `list_models` | Engines + credit cost for a category (`3d` / `image` / `parts-board` / `remesh` / `texture` / `animate`). Call before generating — don't hardcode engines. |\n| `list_animation_presets` | Animation preset ids (engine-specific), with optional substring filter. |\n| `get_credits` | Current credit balance + plan. |\n| `generate_image` | Text → image (+ optional reference image URLs). |\n| `generate_3d_from_text` | Text → 3D model (GLB). |\n| `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. |\n| `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. |\n| `remesh` | Retopologize an existing 3D asset → new asset. |\n| `texture` | Re-texture (PBR) an existing 3D asset → new asset. |\n| `animate` | Auto-rig + animate an existing 3D character → new asset. |\n| `get_asset` | Status + result URLs for one asset. |\n| `wait_for_asset` | Poll until an asset finishes (or times out), then return it. |\n| `list_my_assets` | Browse your generated assets. |\n| `download_asset` | Export a completed 3D asset (`glb` / `fbx` / `obj`) → signed URL. |\n\n## How generation works\n\nGeneration is **asynchronous**:\n\n1. `generate_3d_from_text({ prompt })` → returns an asset `{ id }`.\n2. `wait_for_asset({ asset_id: id })` → polls until `taskStatus === 2` (succeeded).\n3. Read the result URL from `files.model` (GLB) or `files.image` (PNG).\n\n`taskStatus`: `0` pending · `1` processing · `2` succeeded · `3` failed. Result\nURLs are signed and short-lived — download promptly. Errors come back with an\nactionable message (e.g. an unknown engine returns the list of valid names).\n\n## Example (in an agent)\n\n> \"Make a low-poly treasure chest, retopo it to 3k tris, and give me a Unity FBX.\"\n\n```\nlist_models(category=\"3d\")                         → pick an engine\ngenerate_3d_from_text(prompt=\"low-poly treasure chest\")  → { id: A }\nwait_for_asset(asset_id=A)                          → taskStatus 2\nremesh(asset_id=A, polycount=3000)                  → { id: B }\nwait_for_asset(asset_id=B)\ndownload_asset(asset_id=B, format=\"fbx\", texture_preset=\"unity\")  → signed URL\n```\n\n## Use it alongside Blender MCP\n\nRun this next to [`blender-mcp`](https://github.com/ahujasid/blender-mcp) and the\nagent can generate with PicoBerry, then import into Blender in one flow:\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"picoberry\": { \"command\": \"npx\", \"args\": [\"-y\", \"@picoberry/mcp-server\"], \"env\": { \"PICOBERRY_API_KEY\": \"pb_live_...\" } },\n    \"blender\":   { \"command\": \"uvx\", \"args\": [\"blender-mcp\"] }\n  }\n}\n```\n\n## Develop\n\n```bash\nnpm install\nnpm run build      # tsc → dist/\nPICOBERRY_API_KEY=pb_live_... npm start\n```\n\n## Release\n\nRun **Actions → Publish → Run workflow** (or push a `v*` tag). It publishes to\nnpm and then to the official MCP registry, in that order — the registry\nvalidates by fetching the package's npm metadata and matching its `mcpName`\nagainst `server.json`'s `name`, so npm has to land first. A guard step checks\nevery invariant (name/version agreement, namespace casing, version not already\non npm) *before* anything is published, because npm versions are immutable and a\nfailed half-publish burns the number.\n\nBump `version` in **both** `package.json` and `server.json` (`version` and\n`packages[0].version`) — the guard fails the run if they disagree.\n\n**One-time setup — no secrets.** Both publishes authenticate over the workflow's\nGitHub OIDC token (`id-token: write`). There is nothing to store or rotate.\n\nThe only step is telling npm to trust this workflow. On npmjs.com go to\n**@picoberry/mcp-server → Settings → Trusted publishing → GitHub Actions** and\nenter:\n\n| Field | Value |\n|-------|-------|\n| Organization or user | `UModeler` |\n| Repository | `picoberry-mcp` |\n| Workflow filename | `publish.yml` |\n| Environment name | *(leave empty)* |\n| Allowed actions | `npm publish` |\n\nThe workflow filename must match exactly — it is part of what npm verifies.\n\nThe MCP registry needs no setup at all: `mcp-publisher` exchanges the Actions\nOIDC token, and the registry grants `io.github.<repository_owner>/*` from the\ntoken's `repository_owner` claim. That covers `io.github.UModeler/picoberry-mcp`\nand avoids the interactive browser login (which additionally requires org Owner).\n\n> Trusted Publishing needs **npm >= 11.5.1**, so the workflow runs on **Node 24**\n> (npm 11.x). Node 22 still bundles npm 10.9 and would fail — the `node-version`\n> pin is load-bearing. A guard step fails the run early if the runner ever ships\n> an older npm.\n\n> The namespace is compared **byte-exactly** — `io.github.UModeler/...`, matching\n> the GitHub org's login. A lowercased `io.github.umodeler/...` is rejected 403.\n\n**After publishing**, claim the [Glama listing](https://glama.ai/mcp/servers/UModeler/picoberry-mcp)\n— unclaimed servers get limited discoverability, and `awesome-mcp-servers` gates\nits PRs on a Glama badge in CI.\n\n## License\n\nMIT\n",
  "bytes": 7463,
  "sha": "399b17652e0b69e39f891d49ac2b4f998afdc4b645b6bdca5308a7e52d11aec8",
  "repo_slug": "umodeler/picoberry-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_umodeler_picoberry_mcp_d0cdf860/readme"
}