artemotion-mcp

A Model Context Protocol server for ArtEmotion. It exposes the platform's virtual try-on and vision models as MCP tools so any MCP-aware client (Claude Desktop, Cursor, Zed, the Anthropic API's tools, …) can use them.

What it gives you

| Tool | What it does | |------|--------------| | list_tryon_models | List the try-on models + credits-per-job + supported garment types. | | list_vision_models | List the vision models (image Q&A, captioning, NSFW classifier, …). | | start_tryon | Submit a try-on job → returns job_id immediately. | | start_vision | Submit a vision job → returns job_id immediately. | | get_job | Check the status of a job (queued / processing / completed / failed). | | wait_for_job | Poll until the job is done and return the result inline. |

Install

# Issue an API key from your ArtEmotion account → API Keys page.
# Then add this to your MCP client's config file.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "artemotion": {
      "command": "npx",
      "args": ["-y", "artemotion-mcp"],
      "env": {
        "ARTEMOTION_API_KEY": "ae_live_…"
      }
    }
  }
}

Cursor / Zed

Both follow the same mcpServers shape. Drop the same block into their MCP config.

Configuration

| Env var | Required | Default | Notes | |---------|----------|---------|-------| | ARTEMOTION_API_KEY | yes | — | Bearer key, issued from the account API-keys page. | | ARTEMOTION_BASE_URL | no | https://app.artemotion.ai | Point at staging for testing. | | ARTEMOTION_POLL_INTERVAL_MS | no | 2000 | wait_for_job poll cadence. Minimum 500ms. | | ARTEMOTION_POLL_TIMEOUT_MS | no | 300000 (5 min) | wait_for_job default timeout. Per-call override via the tool's timeout_ms input. |

Example session

You: List the try-on models available.
LLM → list_tryon_models  →  [{id: "image-apps-v2/virtual-try-on", credits_per_job: 15, …}, …]

You: Try on the jacket at <garment-url> on the person in <person-url>.
LLM → start_tryon(model_id, person_image_url, garment_image_url, garment_type: "top")
LLM → wait_for_job(job_id, model_id)
LLM ← {status: "completed", images: ["https://..."]}

Development

pnpm install
pnpm dev   # runs src/index.ts via tsx
pnpm build # tsc → dist/

To smoke-test the stdio handshake from a shell:

ARTEMOTION_API_KEY=ae_test_xxx node dist/index.js
# then paste a JSON-RPC initialize request, or wire it up through a real MCP client.

How it works (one paragraph)

Each MCP tool is a thin wrapper around an existing /api/v1/* endpoint on the ArtEmotion backend. Authentication is bearer-token only — the same API key your account already uses for direct REST access. Long-running jobs return a job_id from start_* and complete asynchronously; wait_for_job polls server-side so the LLM doesn't have to make repeated tool calls. Errors from the API are translated to LLM-readable messages (e.g. 402 INSUFFICIENT_CREDITS → "Insufficient credits on the ArtEmotion account.").

License

UNLICENSED (private).