Meshy MCP Server

Servidor MCP Meshy

Servidor Model Context Protocol (MCP) para a plataforma de geração 3D Meshy AI. Permite que agentes de IA criem, gerenciem e baixem modelos 3D, texturas, imagens, personagens com rig e animações por meio de conversa natural.

Recursos

28 ferramentas cobrindo toda a API do Meshy:

Principais Capacidades

• Retentativas seguras (v0.6.3): uma requisição de criação nunca é reenviada após um timeout ou erro do servidor, então uma tarefa nunca é criada e cobrada duas vezes; as verificações de status são repetidas no intervalo sugerido pela API
• Texto para 3D: Gere modelos 3D a partir de descrições em texto (pipeline de preview + refine)
• Imagem para 3D: Converta uma ou várias imagens em modelos 3D
• Meshy 7.1 (v0.6.0): ai_model: "meshy-7.1" (e latest) em text-to-3d, image-to-3d e multi-image-to-3d. geometry_resolution: "standard" | "2k" | "4k" escolhe a passada de geometria (+5 créditos para 2k/4k; multi-image suporta standard/2k). ultra_mode está obsoleto
• Meshy 6 Lite (v0.6.0): ai_model: "meshy-6-lite" — malha rápida de 5 créditos (15 com textura, apenas texturas 2K) em todos os endpoints de geração
• Smart Topology: model_type: "smart-topology" com ai_model: "meshy-t2" em text-to-3d (novo na v0.6.0) e image-to-3d. Malha triangular limpa e com partes separadas, gerada diretamente com 100–15.000 faces (padrão 4.000) por 5 créditos de malha. meshy-t2.5 (v0.6.4) é o modelo Smart Topology mais recente, com detalhes mais nítidos para assets de jogos: 100–30.000 faces (padrão 15.000), mesmo custo
• Textura multi-view em multi-image (v0.6.0): texture_image_urls — 1–4 vistas do mesmo objeto orientam a textura (Meshy 7.1)
• Texturas 8K (v0.5.0): texture_resolution: "2k" | "4k" | "8k" em image-to-3d, multi-image-to-3d, refine de text-to-3d e retexture (8K custa 15 créditos em vez de 10). Substitui a flag hd_texture, agora obsoleta
• Retexture Multi-view (v0.5.0): multiview_image_urls — 1–4 vistas ordenadas do mesmo objeto orientam a textura em vez de uma única referência de estilo (requer Meshy 7)
• Auto-Rigging e Animação: Adicione esqueletos e animações a personagens humanoides. meshy_animate aceita uma ação predefinida, até 10 ações como clipes em um único arquivo, ou um movimento gerado (v0.6.3); meshy_list_animations encontra os ids de ação
• Texto para Movimento (v0.6.3): gere um clipe de movimento a partir de uma descrição (prime FBX, 10 créditos / swift BVH, 3 créditos) e aplique-o a um personagem com rig
• Creative Lab: Uma ferramenta — uma foto → um produto finalizado e pronto para impressão. 9 produtos: figure, lamp, keychain (com name_text gravado), fridge-magnet, vinyl-figure, brick-figure, keycap e (v0.6.3) fidget-pixel e fidget-collapsible. Executa todo o pipeline e retorna apenas o modelo 3D final; as opções de construção e o formato de saída são configuráveis
• Utilitários de Formato e Tamanho: convert (conversão de formato incl. 3MF, 1 crédito), resize (dimensões reais, 1 crédito), uv_unwrap (layout de UV limpo para texturização externa, 5 créditos)
• Modelos de Imagem 2D: text_to_image / image_to_image suportam nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-2-1, nano-banana-pro, gpt-image-2, gpt-image-2-5-flare e gpt-image-2-5-sunburst, com saída de fundo transparente (remove_background). Image-to-image pode editar um resultado anterior por input_task_id
• Suíte de Impressão 3D:
  • analyze_printability — verificação gratuita (watertight, volume, furos, arestas non-manifold, faces degeneradas), além de uma verificação de espessura de parede para um tipo de impressora e tamanho de impressão específicos (v0.6.3)
  • repair_printability — reparo de topologia por 10 créditos (.glb / .gltf / .obj / .fbx / .stl) que também pode espessar paredes finas
  • process_multicolor — 3MF multicolorido por 10 créditos para impressoras AMS/MMU, estilo realistic ou cartoon, com um preset de fatiador para 9 marcas de impressora
  • auto_split (v0.6.3) — 10 créditos: corte um modelo em partes imprimíveis automaticamente, por partes nomeadas ou por cor, com conectores opcionais
• Relatório de uso (v0.6.3): list_usage lista tarefas de API finalizadas com seus créditos (equipes Studio / Enterprise)
• Listagem de tarefas e modelos (v0.6.3): list_tasks lista tarefas de qualquer status de text-to-3d, image-to-3d, multi-image-to-3d, text-to-image e image-to-image por padrão (passe task_types para tarefas de impressão, rigging, animação, movimento, pós-processamento ou Creative Lab); list_models lista modelos 3D finalizados de qualquer tipo que produza modelos (image-to-3d por padrão), cada um com o task_type e os formatos para download. Antes da 0.6.3, list_tasks consultava todos os tipos e list_models listava apenas text-to-3d; veja as mudanças de comportamento no CHANGELOG
• Integração com Fatiadores: Detecta automaticamente 7 fatiadores instalados (OrcaSlicer, Bambu, Creality, Elegoo, Anycubic, PrusaSlicer, Cura; todos exceto Cura abrem 3MF multicolorido) e retorna comandos de inicialização que o agente pode executar
• Organização Inteligente de Arquivos: Salva automaticamente em meshy_output/ com pastas de projeto, metadados e histórico
• Inteligência de Fluxo de Trabalho Integrada: As instruções do servidor guiam o agente pelas cadeias de ferramentas corretas para cada caso de uso

Modelos e Créditos

ai_model não é o mesmo conjunto em todos os endpoints, e latest não resolve para o mesmo modelo em todos os lugares (texto, imagem, multi-imagem, retexture):

Ids legados ainda aceitos: meshy-7 na geração (obsoleto, cobrado como meshy-7.1) e meshy-t1 de imagem única (obsoleto; use meshy-t2). meshy-5 foi aposentado e não é mais aceito.

Custo de geração (preços):

O preview de text-to-3D é cobrado apenas pela malha; o refine adiciona 10 (15 em 8K). geometry_resolution: "2k" ou "4k" (passada Ultra, Meshy 7.1 / latest) adiciona +5; multi-image suporta apenas "2k". ultra_mode está obsoleto e mapeia para "2k". model_type: "lowpoly" é aposentado em 2026-10-30: use smart-topology + meshy-t2.

Smart Topology gera diretamente com target_polycount e pula o remesh: meshy-t2 100–15.000 faces (padrão 4.000), meshy-t2.5 100–30.000 (padrão 15.000). Sem ai_model, model_type: "smart-topology" usa meshy-t2. A saída é apenas triangular. Para modelos padrão, target_polycount requer should_remesh: true e é substituído por decimation_mode.

Retexture custa 10 créditos (15 em 8K). Creative Lab custa 36 créditos por produto (6 + 30; lamp é 30 + 6), exceto keycap, 62 (12 + 50) e fidget-collapsible, 6 (estágio único). Imagens: nano-banana 3, nano-banana-2 6, nano-banana-2-lite 3, nano-banana-2-1 4, nano-banana-pro 9, modelos GPT Image 9 (texto) / 12 (imagem). Outras ferramentas: remesh 5, rig 5, animate 3 por ação, text-to-motion 10 (prime) / 3 (swift), convert 1, resize 1, uv-unwrap 5, analyze-printability grátis, repair-printability 10, multicolor 10, auto-split 10.

Pré-requisitos

• Node.js >= 18
• Uma chave de API do Meshy (obtenha uma aqui — requer plano Pro ou superior)

Instalação

Escolha o que melhor se adapta ao seu fluxo de trabalho — todos produzem a mesma configuração.

Opção 1 · Instalação com Um Comando · Recomendado

add-mcp detecta automaticamente todos os clientes de IA na sua máquina (Cursor, Claude Code, Claude Desktop, Windsurf, Codex, VS Code, Cline, …) e grava a configuração correta em cada um:

npx add-mcp @meshy-ai/meshy-mcp-server --env MESHY_API_KEY=msy_YOUR_API_KEY

Depois que terminar, vá para Ativar para o seu cliente.

Opção 2 · Instalar Pedindo ao Seu Agente de IA

Já está conversando com o Cursor / Claude Code / Codex? Cole este prompt:

Install the Meshy MCP server for me. Docs: https://github.com/meshy-dev/meshy-mcp-server
Use this env var: MESHY_API_KEY=msy_YOUR_API_KEY

O agente executará add-mcp (ou gravará mcp.json diretamente) e avisará quando estiver pronto. Você ainda precisará do passo Ativar para o seu cliente.

Opção 3 · Instalação Manual

{
  "mcpServers": {
    "meshy": {
      "command": "npx",
      "args": ["-y", "@meshy-ai/meshy-mcp-server"],
      "env": { "MESHY_API_KEY": "msy_YOUR_API_KEY" }
    }
  }
}

claude mcp add-json meshy '{"command":"npx","args":["-y","@meshy-ai/meshy-mcp-server"],"env":{"MESHY_API_KEY":"msy_YOUR_API_KEY"}}'

Ativar Após a Instalação

A maioria dos clientes carrega o novo servidor automaticamente, mas Cursor e VS Code exigem uma ativação manual:

Solução de Problemas

• MESHY_API_KEY environment variable is required — retornado por todas as ferramentas quando a chave não chegou ao servidor. Certifique-se de que ela esteja dentro de um bloco "env": {...} no seu mcp.json, e não em args. Reinicie o servidor após corrigir.
• spawn npx ENOENT (Windows) — envolva com cmd /c (veja o bloco do Cursor acima).
• error: unknown option '-y' (Claude Code no Windows) — use claude mcp add-json em vez de claude mcp add … -- npx -y ….
• O Cursor não lista meshy — certifique-se de que mcp.json seja JSON válido (sem vírgulas finais) e reinicie completamente o Cursor.
• Authentication failed: the Meshy API rejected MESHY_API_KEY (401) — a chave está digitada incorretamente, revogada ou expirada. Gere novamente em https://www.meshy.ai/developers/keys, atualize sua configuração e reinicie o servidor.

Configuração

Desenvolvimento

# Clone and install
git clone https://github.com/meshy-dev/meshy-mcp-server.git
cd meshy-mcp-server
npm ci

# Development with hot reload
npm run dev

# Build
npm run build

# Type check
npm run lint

# Build and run offline mocked-request tests (no API key or credits required)
npm test

# Run
npm start

Mantendo um checkout local

Consulte configuração, atualizações e rollback para executar uma build local revisada, fixar versões de pacotes, testar o roteamento de modelos sem chamadas de API pagas e reconectar um cliente com segurança.

Transporte HTTP

Para acesso remoto, execute no modo HTTP:

TRANSPORT=http PORT=3000 npm start

Endpoints:

• POST /mcp — Endpoint do protocolo MCP
• GET /health — Verificação de integridade

Licença

MIT