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

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

Image to 3D

Multi-Image to 3D

Remesh & Export

Retexture

Text to Image

Rigging

Animation

Image to Image

Workflow Helpers

Account

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

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:

Credits

Created by Mr Polti from Wizards.

License

MIT