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