Skip to main content
Glama

meshy-bottube-mcp

BCOS Ready License: MIT

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)

Related MCP server: Rodin Gen-2 MCP Server

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

  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.

Available Tools

15 tools
animate_modelB

Apply a motion to a rigged model -> animated .glb. action_id is from Meshy's library (e.g. 0=Idle, 1=Walking, 4=Attack, 22=Dancing). fps must be one Meshy supports: 24, 25, 30, or 60.

Inputs: rig_task_id (required), action_id (required), fps, timeout.

animate_to_bottubeA

One-shot: a humanoid model -> Meshy rig -> animate (action_id) -> render the MOTION -> BoTTube video. Unlike a turntable, the published clip shows the character performing the action. Always returns a dict. The clip length follows the animation (capped at BoTTube's max).

Inputs: action_id (required), title (required), input_task_id, model_url, +7 more.

frames_to_videoC

Combine numbered PNG frames into a raw H.264 mp4.

Inputs: frames_dir (required), fps, duration.

generate_3d_from_imageA

Image-to-3D: a photo/render (public URL or local file path) -> textured .glb. Returns the local .glb path and the Meshy task id.

Inputs: image (required), texture_prompt, enable_pbr, should_texture, +2 more.

generate_3d_from_imagesB

Multi-image-to-3D: 1-4 reference images (URLs or local paths) of one subject -> a higher-fidelity textured .glb.

Inputs: images (required), texture_prompt, enable_pbr, should_texture, +2 more.

generate_3d_modelA

Generate a 3D model from a text prompt via Meshy.ai (preview → refine).

art_style: realistic | cartoon | low-poly | sculpture. The refine stage TEXTURES the model: enable_pbr (default True) for PBR textures, and texture_prompt for extra texturing guidance (e.g. "weathered bronze, mossy"). Blocks until the textured model is ready; returns its local .glb path and both Meshy task ids.

Inputs: prompt (required), art_style, should_remesh, texture_prompt, +2 more.

get_meshy_task_statusA

Inspect any Meshy task by id. If it SUCCEEDED and download=True and it has a GLB, download it locally and include the path.

Inputs: task_id (required), download.

image_to_bottubeB

One-shot: an image -> Meshy image-to-3D -> turntable -> BoTTube video.

Always returns a dict (ok + watch_url, or ok=False + error/failed_stage + partial artifacts).

Inputs: image (required), title (required), description, tags, +9 more.

meshy_to_bottubeA

One-shot: prompt -> Meshy 3D -> turntable -> video -> BoTTube upload.

Preflights every dependency up front (so a missing Blender/ffmpeg/key can't waste a billed Meshy generation), then runs the whole pipeline in a single working directory.

Always returns a dict. On success: ok=True plus watch_url / watch_url_full and every intermediate path. On a known stage failure: ok=False with error / failed_stage and whatever artifacts were produced before the failure (so nothing is silently lost).

Inputs: prompt (required), title (required), description, tags, +10 more.

prepare_videoC

Make a video meet BoTTube upload constraints (720x720, faststart, audio).

Inputs: video_path (required).

render_turntableA

Render a GLB model as a 360° turntable to PNG frames (requires Blender). Frames are written to a fresh working dir; the path is returned.

Inputs: glb_path (required), frames, resolution.

retexture_modelA

Re-texture an existing model into a new variant. Identify the source by input_task_id (a prior Meshy task) or a public model_url; describe the look with text_style_prompt or image_style_url. Returns the new .glb path.

Inputs: text_style_prompt, image_style_url, input_task_id, model_url, +2 more.

retexture_to_bottubeC

One-shot: re-texture an existing model -> turntable -> BoTTube video. Great for publishing texture variants of one model. Always returns a dict.

Inputs: title (required), text_style_prompt, image_style_url, input_task_id, +10 more.

rig_modelA

Auto-rig a humanoid model for animation (a skeleton). Identify it by input_task_id (a prior Meshy generation) or a public model_url. Returns rig_task_id — feed it to animate_model.

Inputs: input_task_id, model_url, height_meters, timeout.

upload_to_bottubeB

Upload a finished mp4 to BoTTube. tags is comma-separated; category is an optional BoTTube category id (e.g. "comedy", "ai-art", "music").

Note: this uploads whatever local file you point it at, under your own BoTTube API key — intentional, so you can publish videos made elsewhere.

Inputs: video_path (required), title (required), description, tags, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 15 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: individual generation tools (image, multi-image, text), retexturing, rigging, animation, rendering, video preparation, and upload. The one-shot pipeline tools (e.g., animate_to_bottube, image_to_bottube) are differentiated by their input type and are well-described, leaving no ambiguity.

    Naming Consistency5/5

    Tool names consistently use snake_case with a verb_noun pattern (e.g., animate_model, render_turntable, upload_to_bottube). Pipeline tools follow a predictable 'X_to_bottube' convention. The naming is uniform and easy to understand for an agent.

    Tool Count5/5

    With 15 tools, the server covers a complex multi-step workflow (3D generation, rigging, animation, rendering, video creation, upload) without unnecessary bloat. Each tool is justified and the count feels appropriate for its scope.

    Completeness5/5

    The tool set covers the entire pipeline from text/image to 3D model to video upload, including tasks like retexturing, rigging, animation, status checking, and video processing. There are no obvious gaps that would cause agent failures for its intended use case.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers