Meshy MCP Server

An MCP (Model Context Protocol) server that gives AI assistants the power to generate 3D models, textures, and images through the Meshy.ai API.

Ask Claude to "create a 3D model of a medieval castle" and it will handle the entire workflow — generating previews, refining models, remeshing for export, and more — all through natural conversation.

Features

Feature	Description
Text to 3D	Generate 3D models from text descriptions with a preview + refine workflow
Image to 3D	Create 3D models from a single reference image
Multi-Image to 3D	Generate 3D from up to 4 reference images for better accuracy
Remesh & Export	Re-mesh models and export in glb, fbx, obj, usdz, blend, or stl
Retexture	Apply new textures to existing 3D models via text or image style reference
Text to Image	Generate images from text (useful as input for image-to-3D pipelines)
Rigging	Auto-rig humanoid 3D models for animation (GLB format, max 300k faces)
Animation	Apply 500+ animations to rigged models from the Meshy animation library
Image to Image	Transform and edit images using reference images and text prompts
Balance	Check your Meshy credit balance

Prerequisites

• Node.js 18+ (uses native fetch)
• Meshy API Key — sign up at meshy.ai and get your key from API Settings

Installation

From npm

npm install -g meshy-mcp-server

From source

git clone https://github.com/gwizards/meshy-mcp-server.git
cd meshy-mcp-server
npm install
npm run build

Configuration

Claude Code

Add to your project .mcp.json or ~/.claude/settings.json:

{
  "mcpServers": {
    "meshy": {
      "command": "node",
      "args": ["/absolute/path/to/meshy-mcp-server/dist/index.js"],
      "env": {
        "MESHY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Desktop

Add to your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "meshy": {
      "command": "node",
      "args": ["/absolute/path/to/meshy-mcp-server/dist/index.js"],
      "env": {
        "MESHY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Usage

Text-to-3D Workflow

The most common workflow uses wait_for_task to handle polling automatically:

1. Generate preview — text_to_3d_create with mode: "preview" and your prompt
2. Wait for completion — wait_for_task with task_type: "text_to_3d" — returns download URLs when done
3. Refine the model — text_to_3d_create with mode: "refine" and the preview_task_id
4. Wait again — wait_for_task returns the final model with download URLs
5. Export (optional) — remesh_create then wait_for_task

Image-to-3D Pipeline

Combine text-to-image with image-to-3D for a fully text-driven pipeline:

1. Generate reference image — text_to_image_create with your description
2. Wait for image — wait_for_task with task_type: "text_to_image"
3. Generate 3D from image — image_to_3d_create with the resulting image URL
4. Wait for 3D model — wait_for_task with task_type: "image_to_3d"

Rigging & Animation Pipeline

1. Generate 3D model — any _create tool
2. Rig the model — rigging_create with the task ID or model URL
3. Wait for rigging — wait_for_task with task_type: "rigging"
4. Animate — animation_create with the rigging task ID and action ID
5. Wait for animation — wait_for_task with task_type: "animation"

Example Prompts

Once configured, you can ask Claude things like:

• "Generate a 3D model of a low-poly fox"
• "Create a medieval sword with PBR textures and export as FBX"
• "Take this image and turn it into a 3D model"
• "Retexture my model with a cyberpunk style"
• "Rig this model and apply a walking animation"
• "Transform this photo into a different style"
• "How many credits do I have left?"

Available Tools

Text to 3D

Tool	Description
text_to_3d_create	Generate 3D from text (preview or refine mode)
text_to_3d_get	Check task status and retrieve results
text_to_3d_list	List tasks with pagination
text_to_3d_delete	Delete a task

Image to 3D

Tool	Description
image_to_3d_create	Generate 3D from a single image URL or base64 data URI
image_to_3d_get	Check task status
image_to_3d_list	List tasks
image_to_3d_delete	Delete a task

Multi-Image to 3D

Tool	Description
multi_image_to_3d_create	Generate 3D from 1-4 reference images
multi_image_to_3d_get	Check task status
multi_image_to_3d_list	List tasks
multi_image_to_3d_delete	Delete a task

Remesh & Export

Tool	Description
remesh_create	Remesh and export to glb, fbx, obj, usdz, blend, or stl
remesh_get	Check task status
remesh_list	List tasks
remesh_delete	Delete a task

Retexture

Tool	Description
retexture_create	Apply new textures via text prompt or style image
retexture_get	Check task status
retexture_list	List tasks
retexture_delete	Delete a task

Text to Image

Tool	Description
text_to_image_create	Generate images (models: nano-banana, nano-banana-pro)
text_to_image_get	Check task status
text_to_image_list	List tasks
text_to_image_delete	Delete a task

Rigging

Tool	Description
rigging_create	Auto-rig a humanoid 3D model (GLB, max 300k faces)
rigging_get	Check rigging task status
rigging_delete	Delete a rigging task

Animation

Tool	Description
animation_create	Apply animation to a rigged model (500+ actions)
animation_get	Check animation task status
animation_delete	Delete an animation task

Image to Image

Tool	Description
image_to_image_create	Transform images with text prompts and references
image_to_image_get	Check task status
image_to_image_list	List tasks
image_to_image_delete	Delete a task

Workflow Helpers

Tool	Description
wait_for_task	Poll any task until completion — replaces manual _get loops

Account

Tool	Description
get_balance	Check your Meshy credit balance

Task Lifecycle

All generation tasks follow the same async pattern:

CREATE → PENDING → IN_PROGRESS → SUCCEEDED / FAILED

• PENDING — Task is queued
• IN_PROGRESS — Generation is running (progress field shows 0-100%)
• SUCCEEDED — Complete. model_urls, texture_urls, and thumbnail_url are available
• FAILED — Check task_error.message for details
• CANCELED — Task was canceled

Error Handling

All tools return structured errors via MCP's isError flag instead of raw exceptions:

• Validation errors — Missing required fields (e.g., prompt in preview mode) return clear messages
• API errors — HTTP errors from Meshy include status code and response body
• Network errors — Transient failures (429, 500, 502, 503, 504) are retried automatically with exponential backoff (1s, 2s, 4s — max 3 retries). 429 responses respect the Retry-After header

Project Structure

meshy-mcp-server/
├── src/
│   ├── index.ts              # MCP server setup, 36 tool definitions, validation
│   └── meshy-client.ts       # Meshy API client with retry logic
├── tests/
│   ├── meshy-client.test.ts  # Client retry/error tests
│   └── tools.test.ts         # End-to-end MCP tool tests
├── .github/workflows/ci.yml  # GitHub Actions CI (Node 18/20/22)
├── dist/                     # Compiled output (generated by npm run build)
├── CLAUDE.md                 # Project conventions for AI assistants
├── package.json
├── tsconfig.json
├── vitest.config.ts
└── README.md

Tech Stack

Component	Technology
Language	TypeScript (strict mode)
Runtime	Node.js 18+
MCP SDK	@modelcontextprotocol/sdk ^1.27.1
Validation	Zod ^4.3.6
Testing	Vitest
Transport	stdio
Module System	ES modules
Build	tsc to ES2022

Development

npm run dev    # Run with tsx (auto-reload)
npm run build  # Compile TypeScript
npm test       # Run test suite
npm start      # Run compiled version

API Reference

This server wraps the Meshy API v1/v2. Key endpoints used:

Meshy API	Server Tools
POST /openapi/v2/text-to-3d	text_to_3d_create
POST /openapi/v1/image-to-3d	image_to_3d_create
POST /openapi/v1/multi-image-to-3d	multi_image_to_3d_create
POST /openapi/v1/remesh	remesh_create
POST /openapi/v1/retexture	retexture_create
POST /openapi/v1/text-to-image	text_to_image_create
POST /openapi/v1/rigging	rigging_create
POST /openapi/v1/animations	animation_create
POST /openapi/v1/image-to-image	image_to_image_create
GET /openapi/v1/balance	get_balance

Credits

Created by Mr Polti from Wizards.

License

MIT