GoModelHub 3D MCP

MCP server for the GoModelHub 3D generation API. Use it in Cursor and other Agents with natural language.

Tool	Description
generate_3d	Submit a 3D job; returns taskId
get_3d_status	Poll task status once
generate_3d_and_wait	Submit and poll until done (recommended)

Requires Node.js 18+, a platform API Key (gk- / sk-), and a modelCode from Model Marketplace (e.g. hyper3d).

Set your default model once in mcp.json so Agents do not need to pass model every time. You can still override model in a single call when needed.

中文文档

---

Default model in mcp.json

Mode	Where to set	Example
Remote MCP	headers	"X-GoModelHub-Default-Model": "hyper3d"
Local MCP	env	"GOMODELHUB_DEFAULT_MODEL": "hyper3d"

Use the modelCode shown in Model Marketplace for your Key (do not add a tp- prefix).

---

Option 1: Remote MCP (recommended, zero install)

Limitation: Remote MCP does not support local imagePath. For image-to-3D, use a public image URL; for local image files, use the local MCP below.

Cursor → Settings → MCP → edit mcp.json:

{
  "mcpServers": {
    "gomodelhub-3d": {
      "url": "https://login.gomodelhub.com/mcp/3d",
      "headers": {
        "Authorization": "Bearer gk-your-platform-key",
        "X-GoModelHub-Default-Model": "hyper3d"
      }
    }
  }
}

See examples/mcp.remote.json.

---

Option 2: Local MCP (supports imagePath)

1. Install (one-time per machine)

git clone https://github.com/kelouer/GoModelHub-MCP.git
cd GoModelHub-MCP
npm install
npm install -g .

Windows: powershell -ExecutionPolicy Bypass -File scripts/install-global.ps1
macOS/Linux: bash scripts/install-global.sh

Verify: where gomodelhub-3d-mcp (Windows) or which gomodelhub-3d-mcp.

2. Configure

{
  "mcpServers": {
    "gomodelhub-3d": {
      "command": "gomodelhub-3d-mcp",
      "env": {
        "GOMODELHUB_BASE_URL": "https://login.gomodelhub.com",
        "GOMODELHUB_API_KEY": "gk-your-platform-key",
        "GOMODELHUB_DEFAULT_MODEL": "hyper3d"
      }
    }
  }
}

See examples/mcp.local.json. Save and Refresh in the MCP panel.

3. Local image (image-to-3D)

{
  "model": "v3.1-20260211",
  "imagePath": "D:/photos/chair.jpg",
  "mode": "image"
}

Supports jpg / png / webp, max 50MB per file.

---

Comparison

	Remote MCP	Local MCP
Install	None	npm install -g .
Text-to-3D	✅	✅
Public image URL	✅	✅
Local imagePath	❌	✅

---

Troubleshooting

Symptom	Fix
disconnected	Run global install; ensure gomodelhub-3d-mcp is on PATH
Missing GOMODELHUB_BASE_URL	Check env in mcp.json
model is required	Add GOMODELHUB_DEFAULT_MODEL / X-GoModelHub-Default-Model, or pass model in the tool call
HTTP 401 / 403	Invalid key or insufficient quota
Remote image-to-3D fails	Do not use imagePath; use public image URL or local MCP

License

MIT — see LICENSE.