<div align="center">

<h1>meshy-mcp</h1>

<p><strong>Generate 3D models and environments inside Claude — powered by Meshy AI</strong></p>

<p>The first MCP server that gives Claude native 3D generation capabilities.<br/>
Text to 3D · Image to 3D · AI textures · 3D website environments · GLB / FBX / USDZ export</p>

<p>
  <a href="https://github.com/zyadhajaji/meshy-mcp/actions/workflows/ci.yml">
    <img src="https://github.com/zyadhajaji/meshy-mcp/actions/workflows/ci.yml/badge.svg" alt="CI" />
  </a>
  <img src="https://img.shields.io/badge/MCP-compatible-6f42c1?logo=anthropic" alt="MCP" />
  <img src="https://img.shields.io/badge/Meshy_AI-powered-ff6b35" alt="Meshy AI" />
  <img src="https://img.shields.io/badge/Claude_Desktop-ready-191919?logo=anthropic" alt="Claude Desktop" />
  <img src="https://img.shields.io/badge/Node.js-20+-339933?logo=node.js" alt="Node.js 20+" />
  <img src="https://img.shields.io/badge/TypeScript-5-3178c6?logo=typescript" alt="TypeScript" />
  <img src="https://img.shields.io/badge/license-MIT-22c55e" alt="MIT" />
</p>

<p>
  <a href="#-quick-start">Quick Start</a> ·
  <a href="#-tools">Tools</a> ·
  <a href="#-use-cases">Use Cases</a> ·
  <a href="docs/setup.md">Full Setup</a> ·
  <a href="docs/tools.md">Tool Reference</a> ·
  <a href="examples/">Examples</a>
</p>

</div>

---

## What is this?

**meshy-mcp** is a [Model Context Protocol](https://modelcontextprotocol.io) server that connects Claude to the [Meshy AI](https://meshy.ai) 3D generation API.

Once connected to Claude Desktop (or any MCP client), you can say:

> *"Generate a 3D model of a vintage leather messenger bag"*
> *"Turn this product photo into a 3D model"*
> *"Apply a carbon fiber texture to this model"*
> *"Build me a 3D showroom environment for my clothing brand"*

…and Claude will call Meshy, poll until the model is ready, and hand you back download links for GLB, FBX, OBJ, and USDZ files — all without leaving the conversation.

---

## Quick Start

### 1. Get a Meshy API key

Sign up at [app.meshy.ai](https://app.meshy.ai) → Settings → API Keys → Generate Key.

### 2. Add to Claude Desktop

Open your config file:
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "meshy-3d": {
      "command": "npx",
      "args": ["-y", "meshy-mcp"],
      "env": {
        "MESHY_API_KEY": "msy_your_key_here"
      }
    }
  }
}
```

Restart Claude Desktop. Done — Claude now has 3D generation tools.

> See [docs/setup.md](docs/setup.md) for custom MCP clients, running from source, and troubleshooting.

---

## Tools

Six tools are exposed to Claude:

| Tool | What it does |
|---|---|
| `generate_3d_model` | Text → 3D model (GLB, FBX, OBJ, USDZ) |
| `refine_3d_model` | Upgrade preview to production quality with PBR textures |
| `generate_3d_from_image` | Image URL → 3D model |
| `add_texture` | Apply AI-generated textures + PBR maps to any model |
| `check_task_status` | Poll status of any running task |
| `list_3d_models` | List recently generated models |

Full parameter reference: [docs/tools.md](docs/tools.md)

---

## Demo prompts

Paste any of these into Claude after connecting meshy-mcp:

```
Generate a 3D model of a puffer jacket with a reflective quilted surface, realistic style, quad topology.
```
```
Turn this image into a 3D model and apply a woven denim texture: https://example.com/jacket.jpg
```
```
Generate a minimalist luxury showroom environment — white walls, concrete floor, warm spotlights — for a clothing brand website.
```
```
Generate a low-poly voxel sneaker for a game. Target 5000 polygons.
```
```
Create a 3D wristwatch model, then refine it to production quality with PBR textures.
```

---

## Use Cases

### 3D product visualization
Turn product descriptions or photos into 3D assets for e-commerce, AR try-on, and marketing. Works for fashion, furniture, electronics, and more.

### 3D website environments
Generate scene props and environments, export GLB files, and embed them with Three.js or Babylon.js. Build interactive 3D landing pages, virtual showrooms, and immersive brand experiences — all by describing them to Claude.

### Print-on-demand & clothing brands
Generate photorealistic garment mockups, brand kit 3D assets, and complete lookbook scenes. Use alongside [ThreadForge](https://github.com/zyadhajaji/threadforge) for the full clothing brand workflow.

### Game & metaverse assets
Generate props, characters, and environment pieces with game-ready topology. Export FBX for Unreal Engine or Unity.

### AR & spatial computing
USDZ output works with Apple AR Quick Look and visionOS. Generate and share AR-viewable 3D models directly from Claude.

---

## How Meshy built a $20M+ business on this API

Meshy is not just a tool — it's one of the most well-engineered AI data flywheels in the 3D space. Understanding how they built it changes how you think about using and building on top of their API.

**The short version:**
- The 4-variant limit per generation is not a cost-saving measure — it's a training data architecture decision
- Every model you pick over the others is a free preference signal (RLHF without asking)
- The free tier exists to collect data, not out of generosity
- After millions of generations, Meshy holds a `(prompt → accepted output)` dataset that no competitor can buy
- Every developer who builds on the API (like this repo) extends their distribution for free

> Read the full breakdown: [docs/how-meshy-built-a-3d-ai-empire.md](docs/how-meshy-built-a-3d-ai-empire.md)
>
> Covers: the technical stack, the data flywheel, the Midjourney parallel, pricing power risk, self-hosting alternatives, and the exact blueprint for replicating this in any vertical.

---

## Architecture

```
meshy-mcp/
├── src/
│   ├── index.ts           # Entry point
│   ├── server.ts          # MCP server + tool router
│   ├── meshy/
│   │   ├── client.ts      # Meshy REST API client
│   │   ├── types.ts       # Full TypeScript type definitions
│   │   └── poller.ts      # Async task completion poller
│   ├── tools/
│   │   ├── text-to-3d.ts  # generate_3d_model
│   │   ├── refine-3d.ts   # refine_3d_model
│   │   ├── image-to-3d.ts # generate_3d_from_image
│   │   ├── texture.ts     # add_texture
│   │   └── status.ts      # check_task_status + list_3d_models
│   └── utils/
│       └── format.ts      # Markdown output formatters
├── docs/                  # Setup + tool reference
├── examples/              # Claude Desktop config + prompt walkthroughs
├── CLAUDE.md              # AI agent context (for Claude Code)
└── .env.example
```

**Protocol:** stdio MCP (compatible with Claude Desktop, Cursor, Zed, and any MCP client)
**Language:** TypeScript 5, ESM, Node.js 20+
**Dependencies:** `@modelcontextprotocol/sdk`, `zod` — nothing else

---

## Environment Variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `MESHY_API_KEY` | ✅ | — | From app.meshy.ai → Settings → API Keys |
| `MESHY_BASE_URL` | — | `https://api.meshy.ai` | Override API base URL |
| `MESHY_POLL_TIMEOUT_SECONDS` | — | `300` | Max wait per task |
| `MESHY_POLL_INTERVAL_SECONDS` | — | `3` | Polling frequency |

---

## Contributing

1. Fork → create a branch → `npm run typecheck` before committing
2. New tool? Follow the pattern in any existing file in `src/tools/`
3. Open a PR — see [CLAUDE.md](CLAUDE.md) for the full contributor guide

---

## Related

- [Meshy AI](https://meshy.ai) — the 3D generation API powering this server
- [Model Context Protocol](https://modelcontextprotocol.io) — the open protocol for Claude tool use
- [ThreadForge](https://github.com/zyadhajaji/threadforge) — clothing brand mockup platform (pairs well with meshy-mcp)
- [Claude Desktop](https://claude.ai/download) — the MCP client used in examples
- [How Meshy Built a $20M+ 3D AI Business](docs/how-meshy-built-a-3d-ai-empire.md) — deep dive into the data flywheel, training strategy, and business model

---

## License

[MIT](LICENSE)

---

<div align="center">

**Keywords:** MCP server 3D generation · Claude 3D model tool · Meshy AI MCP · text to 3D Claude · image to 3D AI · 3D environment generator · Claude Desktop MCP · AI 3D design tool · model context protocol 3D · Meshy API integration · AI texture generation · GLB FBX generator · Three.js asset generation · 3D website environment AI · anthropic tool use 3D

</div>