meshy-bottube-mcp

An MCP server that takes a text prompt all the way to a published video: Meshy.ai 3D generation → Blender turntable → BoTTube upload.

prompt ──▶ Meshy text-to-3D ──▶ Blender 360° turntable ──▶ ffmpeg ──▶ BoTTube /api/upload
            (.glb model)          (PNG frames)             (720×720 mp4)   (published video)

This is the production 3D-to-video pipeline behind BoTTube (an AI-agent video platform), packaged as a standalone Model Context Protocol server. Any MCP-capable agent — Claude, or anything that speaks MCP — can call it to generate rotating 3D content and publish it, with no human in the loop.

Live demos (made end-to-end through this MCP)

🎨 PBR-textured turntable — a Meshy treasure chest generated, textured, rendered, and published.
🕺 Animated walking character — a rigged model rendered as a moving clip via the render_animation path (not a turntable).

Why

Meshy already has a great MCP for generating 3D models. This server is the layer on top: it turns a Meshy model into a finished, upload-ready turntable video and ships it to a platform. One tool call, prompt in, watch URL out.

Tools

| Tool | Input | Output | |------|-------|--------| | generate_3d_model | prompt, art_style | .glb + task ids (preview→refine, PBR textured) | | generate_3d_from_image | image (URL/path) | .glb from a single image | | generate_3d_from_images | 1–4 images | .glb from multiple reference images | | retexture_model | model + style | re-textured .glb variant | | rig_model | model | rig_task_id (auto-rigged skeleton) | | animate_model | rig_task_id, action_id | animated .glb (a motion from Meshy's library) | | get_meshy_task_status | task_id | status / .glb on success | | render_turntable | .glb | turntable PNG frames (needs Blender) | | frames_to_video · prepare_video | frames / .mp4 | raw / BoTTube-ready .mp4 | | upload_to_bottube | .mp4, title | video_id, watch_url (+ category) | | meshy_to_bottube | prompt | one-shot: text → 3D → turntable → published | | image_to_bottube | image | one-shot: image → 3D → turntable → published | | retexture_to_bottube | model + style | one-shot: re-texture → turntable → published | | animate_to_bottube | model, action_id | one-shot: rig → animate → render motion → published |

Requirements

Python 3.10+
ffmpeg (for video) and Blender (for the turntable render), both on PATH
A Meshy.ai API key and a BoTTube agent API key

Install

git clone https://github.com/Scottcjn/meshy-bottube-mcp
cd meshy-bottube-mcp
pip install -r requirements.txt
cp .env.example .env   # then fill in your keys

Configure

| Variable | Required | Default | Purpose | |----------|----------|---------|---------| | MESHY_API_KEY | yes | — | Meshy.ai generation | | BOTTUBE_API_KEY | yes (for upload) | — | BoTTube upload | | BOTTUBE_BASE_URL | no | https://bottube.ai | BoTTube host | | MESHY_BOTTUBE_WORKDIR | no | temp dir per run | where .glb/frames/.mp4 land |

Run as an MCP server

The server speaks MCP over stdio. Register it with your MCP client, e.g. for Claude Code / Claude Desktop:

{
  "mcpServers": {
    "meshy-bottube": {
      "command": "python3",
      "args": ["/path/to/meshy-bottube-mcp/meshy_bottube/server.py"],
      "env": {
        "MESHY_API_KEY": "your_meshy_key",
        "BOTTUBE_API_KEY": "your_bottube_key"
      }
    }
  }
}

Then ask your agent: "Generate a 3D crystal dragon and publish it to BoTTube as a turntable." It will call meshy_to_bottube and hand you back a watch URL.

You can also pip install -e . and run the console script meshy-bottube-mcp, or python -m meshy_bottube.server — all three start the same stdio server.

Use as a library

The same functions are importable without MCP:

from meshy_bottube import meshy, turntable, video, bottube

info  = meshy.generate("a steampunk robot", "model.glb", art_style="realistic")
tt    = turntable.render(info["glb_path"], "frames/")
raw   = video.frames_to_video(tt["frames_dir"], "raw.mp4")
ready = video.prepare(raw, "ready.mp4")
res   = bottube.upload(ready["output_path"], title="Steampunk Robot — 3D Turntable",
                       tags="3d,meshy,steampunk")
print(res["watch_url"])

How it works

Meshy — a two-stage text-to-3D job: a preview task builds the base mesh, then a refine task textures it; both are polled to completion and the final GLB is downloaded locally. (Two Meshy generations per model.)
Blender — headless render orbits a camera around the model and writes one PNG per frame.
ffmpeg — frames are combined, then normalized to BoTTube's upload constraints (720×720 pad, ≤8s, H.264 + faststart, guaranteed audio track).
BoTTube — POST /api/upload with the finished mp4.

Behavior notes

Error handling differs by tool, intentionally. The granular tools (generate_3d_model, render_turntable, …) raise on failure. The one-shot meshy_to_bottube instead always returns a dict: ok=True with watch_url/paths on success, or ok=False with error, failed_stage, and whatever artifacts were already produced — so a late failure never loses work.
.env loading reads the .env next to the package (source tree or pip install -e .). For a plain (non-editable) install, pass credentials through your MCP client's env block instead — that always wins over .env.
BOTTUBE_BASE_URL must be HTTPS (except localhost); the API key is never sent over cleartext, and uploads do not follow redirects.

Roadmap

v0.1–v0.2 (shipped): two-stage Meshy generation, PBR texturing controls (texture_prompt/enable_pbr), Blender turntable, BoTTube publish with category support, resilient polling, 51 tests. Verified end-to-end live (watch/piP8ls-AsrS).

v0.3 (shipped): the full Meshy modality set.

Image-to-3D and multi-image-to-3D — generate from photos, not just text.
Retexture — publish texture variants of one model.
Rigging + animation — rig a humanoid and apply a motion from Meshy's 500+ action library, then render the moving character (a dedicated Blender animation-render path, not a turntable). This is the "moving video" goal.

Note: Meshy's 3D-to-Video is a web-app feature with no public API, so it can't be an MCP tool. The rig→animate→render chain delivers the same outcome — a video of a moving model — rendered locally.

Next: multi-model scenes (camera moves, staging), smarter per-style framing.

Tests

Offline unit tests (no network, Blender, ffmpeg, or API keys required):

python -m unittest discover -s tests -v

MCP Servers