@xinyuai/mcp-server

A Model Context Protocol server that exposes XinYuAi's generation capabilities (image, video, audio, text, and editing) to any MCP-compatible agent — Claude Desktop, Cursor, Windsurf, Cline, etc.

It is a thin HTTP wrapper over the existing XinYuAi generation API. Every call authenticates with a user-level API key (xys_live_...) and runs on that user's own balance, concurrency limits, model locks, and compliance rules — the exact same path as the web app. No third-party provider keys are ever exposed.

Prerequisites

• Node.js >= 18
• A XinYuAi API key. Create one in Settings → API Keys (the plaintext key is shown once at creation time).

Install

No install step is required — the client configs below launch the server with npx, which fetches and runs the latest published version automatically.

To install it explicitly:

npm install -g @xinyuai/mcp-server   # exposes the `xinyu-mcp` command

pnpm install --ignore-workspace
pnpm build

This produces dist/index.js (the executable MCP server, bin name xinyu-mcp).

Configuration

The server reads two environment variables:

| Variable | Required | Default | Description | |---|---|---|---| | XINYU_API_KEY | yes | — | Your XinYuAi user API key (xys_live_...). | | XINYU_BASE_URL | no | https://xinyuai.app | Base URL of the XinYuAi server. Use http://localhost:3001 for local dev. |

Client configuration

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "xinyu": {
      "command": "npx",
      "args": ["-y", "@xinyuai/mcp-server"],
      "env": {
        "XINYU_API_KEY": "xys_live_xxxxxxxxxxxxxxxx",
        "XINYU_BASE_URL": "https://xinyuai.app"
      }
    }
  }
}

Cursor / Windsurf / Cline

These use the same shape. Example (.cursor/mcp.json or Windsurf MCP config):

{
  "mcpServers": {
    "xinyu": {
      "command": "npx",
      "args": ["-y", "@xinyuai/mcp-server"],
      "env": { "XINYU_API_KEY": "xys_live_xxxx" }
    }
  }
}

Restart the client; the xinyu_* tools will appear.

Tools

| Tool | Backend route | Notes | |---|---|---| | xinyu_generate_image | POST /api/generate/image | text-to-image / image-to-image | | xinyu_generate_video | POST /api/generate/video | Kling / Seedance / WAN / Grok / LTX / Gemini Omni | | xinyu_generate_audio | POST /api/generate/audio | ElevenLabs TTS | | xinyu_generate_text | POST /api/generate/text | Gemini / ChatGPT / DeepSeek (returns full text) | | xinyu_enhance | POST /api/generate/enhance | Topaz upscale | | xinyu_remove_bg | POST /api/generate/rembg | background removal | | xinyu_outpaint | POST /api/generate/outpaint | expand canvas | | xinyu_image_edit | POST /api/generate/image-edit | prompt-based edit | | xinyu_video_edit | POST /api/generate/video-edit | Kling O3 video-to-video (source >= 720px tall) | | xinyu_video_action | POST /api/generate/video-action | upscale / extend a Grok video | | xinyu_get_job | GET /api/jobs/:id | poll one job | | xinyu_list_jobs | GET /api/jobs | recent jobs | | xinyu_balance | GET /api/billing/balance | Xins balance | | xinyu_list_models | GET /api/models | model catalog |

Async behavior (no result is ever lost)

Generation tools enqueue a job and, by default, wait until it finishes before returning the asset URL(s). The wait timeout defaults to 300s (images/audio) or 1200s (video) and can be raised up to 3600s — the platform's own ~60-minute ceiling.

Timing out is safe: the tool returns status: "RUNNING" plus a jobId, and the job keeps running server-side. Poll it with xinyu_get_job(jobId) until SUCCEEDED/FAILED — do not poll the HTTP API directly. On success the asset is saved to your account (and the canvas, when place_on_canvas); a failed or timed-out job (~60 min) is auto-refunded, so never re-issue a generation just because the wait timed out.

Every media generation requires a project_id (canvas); set wait: false to skip waiting and get the jobId immediately.

Example

In an MCP-enabled agent:

"Use nano-banana-2 to generate a cyberpunk city at 2K, 16:9."

The agent calls xinyu_generate_image with { prompt, model_id: "nano-banana-2", image_size: "2K", aspect_ratio: "16:9" }, waits for the job, and returns the image URL.

Development

pnpm dev        # run from source with tsx
pnpm typecheck  # type-check only