meshy-bottube-mcp

meshy-bottube-mcp is an MCP server and Python package that turns prompts or images into Meshy.ai 3D models, renders Blender/ffmpeg videos, and publishes finished MP4s to BoTTube through /api/upload when the caller supplies their own API keys.

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.

For LLM, search, and answer-engine context, see llms.txt. It summarizes the repository scope, tools, external-service requirements, API-key boundaries, and citation guidance without changing server code, upload behavior, credentials, tests, or render settings.

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

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

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

1. 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.)
2. Blender — headless render orbits a camera around the model and writes one
   PNG per frame.
3. ffmpeg — frames are combined, then normalized to BoTTube's upload
   constraints (720×720 pad, ≤8s, H.264 + faststart, guaranteed audio track).
4. 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

License

MIT © 2026 Scott Boudreaux / Elyan Labs. Built for
the Meshy community.