meshy-mcp

Meshy MCP Server

MCP (Model Context Protocol) server that exposes Meshy AI's auto-rigging and animation API as tools for Claude and other MCP clients.

Features

• Auto-rigging: Convert static GLB/FBX humanoid models into rigged characters with skeletons
• Animation: Apply animations from Meshy's library to rigged characters
• Async polling: Built-in polling with exponential backoff for long-running tasks
• Balance checking: Monitor API credit balance

Installation

npm install meshy-mcp

Or run directly with npx:

npx meshy-mcp

Configuration

Set the MESHY_API_KEY environment variable:

export MESHY_API_KEY=msy_your_api_key_here

Get your API key from Meshy API Settings.

Available Tools

Tool	Description
meshy_create_rigging_task	Start auto-rigging job for a 3D humanoid model
meshy_get_rigging_task	Get rigging task status and results
meshy_poll_rigging_task	Poll rigging task until completion (with timeout)
meshy_delete_rigging_task	Cancel/delete a rigging task
meshy_create_animation_task	Apply animation to rigged character
meshy_get_animation_task	Get animation task status
meshy_get_balance	Check API credit balance

Usage with Claude Code

Add to your .mcp.json or MCP proxy configuration:

{
  "mcpServers": {
    "meshy": {
      "command": "npx",
      "args": ["-y", "meshy-mcp"],
      "env": {
        "MESHY_API_KEY": "${MESHY_API_KEY}"
      }
    }
  }
}

Example Workflow

1. Check balance first

meshy_get_balance()

2. Create a rigging task

meshy_create_rigging_task(
  model_url="https://example.com/character.glb",
  height_meters=1.8
)

Returns: { "task_id": "task-uuid-here" }

3. Poll for completion

meshy_poll_rigging_task(
  task_id="task-uuid-here",
  timeout_ms=300000
)

Returns task with output URLs when complete:

{
  "success": true,
  "task": {
    "id": "task-uuid-here",
    "status": "SUCCEEDED",
    "progress": 100,
    "result": {
      "rigged_character_glb_url": "https://assets.meshy.ai/...",
      "rigged_character_fbx_url": "https://assets.meshy.ai/...",
      "basic_animations": {
        "walking_glb_url": "https://...",
        "running_glb_url": "https://..."
      }
    }
  }
}

4. Apply additional animation

meshy_create_animation_task(
  rig_task_id="task-uuid-here",
  action_id=1,
  fps=30
)

Tool Parameters

meshy_create_rigging_task

Parameter	Type	Required	Description
model_url	string	*	Publicly accessible GLB file URL
input_task_id	string	*	Completed Meshy task ID (alternative to model_url)
height_meters	number	No	Character height in meters (0.1-10, default: 1.7)

* Either model_url or input_task_id is required

meshy_poll_rigging_task

Parameter	Type	Required	Description
task_id	string	Yes	The rigging task ID to poll
timeout_ms	number	No	Maximum wait time (10000-600000, default: 300000)

meshy_create_animation_task

Parameter	Type	Required	Description
rig_task_id	string	Yes	Completed rigging task ID
action_id	number	Yes	Animation action ID from Meshy library
fps	number	No	Target frame rate (24, 25, 30, or 60)

Supported Models

Auto-rigging works best with:

• Textured humanoid (bipedal) models
• GLB or FBX format
• Clear limb and body structure
• Standard proportions

Not recommended for:

• Untextured meshes
• Non-humanoid assets (animals, objects, vehicles)
• Characters with unclear body structure
• Very stylized proportions

Error Handling

All tools return structured error responses:

{
  "success": false,
  "error": "Meshy API Error (401): Invalid API key"
}

Common error codes:

• 401: Invalid or missing API key
• 404: Task not found
• 408: Polling timeout (task still processing)
• 429: Rate limit exceeded
• 500: Server error or task failed

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Watch mode
npm run build:watch

License

MIT